@williambeto/ai-workflow 2.4.8 → 2.6.3

package/src/core/validation/quality-guard.js

@@ -1,251 +0,0 @@
-import { execSync } from "node:child_process";
-import fs from "node:fs/promises";
-import path from "node:path";
-import { MergeGate } from "../gates/merge-gate.js";
-
-const PROTECTED_BRANCHES = new Set(["main", "master"]);
-
-function normalizePath(file) {
-  return String(file || "").trim().replaceAll("\\", "/");
-}
-
-function parseStatusLine(line) {
-  const value = String(line || "");
-  const match = value.match(/^(?:[ MADRCU?!]{2}\s+|[MADRCU?!]\s+)(.+)$/);
-  if (!match) return "";
-  const candidate = match[1].trim();
-  const renamed = candidate.includes(" -> ") ? candidate.split(" -> ").at(-1) : candidate;
-  return normalizePath(renamed);
-}
-
-function isManagedChangePath(file = "") {
-  return /(^|\/)(node_modules|vendor|dist|coverage|\.cache)(\/|$)/.test(normalizePath(file));
-}
-
-async function exists(target) {
-  try {
-    await fs.access(target);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export { parseStatusLine };
-
-/**
- * QualityGuard verifies objective delivery safety. It does not grade prose or
- * require ceremonial workflow files.
- */
-export class QualityGuard {
-  constructor({ cwd, taskSlug = null, mode = null, evidenceWillBePersisted = false } = {}) {
-    this.cwd = cwd;
-    this.taskSlug = taskSlug;
-    this.mode = mode;
-    this._changedFiles = null;
-    this._hasHead = null;
-    this.evidenceWillBePersisted = evidenceWillBePersisted;
-  }
-
-  runGit(command) {
-    return execSync(command, {
-      cwd: this.cwd,
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "pipe"]
-    }).trim();
-  }
-
-  hasGitHead() {
-    if (this._hasHead !== null) return this._hasHead;
-    try {
-      this.runGit("git rev-parse --verify HEAD");
-      this._hasHead = true;
-    } catch {
-      this._hasHead = false;
-    }
-    return this._hasHead;
-  }
-
-  getCurrentBranch() {
-    try {
-      return this.runGit("git branch --show-current") || "unknown";
-    } catch {
-      return "unknown";
-    }
-  }
-
-  getChangedFiles() {
-    if (this._changedFiles) return this._changedFiles;
-    const files = new Set();
-    try {
-      if (this.hasGitHead()) {
-        this.runGit("git diff --name-only HEAD")
-          .split("\n")
-          .map(normalizePath)
-          .filter(Boolean)
-          .forEach((file) => files.add(file));
-      }
-      this.runGit("git status --short --untracked-files=all")
-        .split("\n")
-        .map(parseStatusLine)
-        .filter(Boolean)
-        .filter((file) => !isManagedChangePath(file))
-        .forEach((file) => files.add(file));
-    } catch {
-      // A non-git consumer may still run validation commands. Branch safety is
-      // reported as unavailable rather than fabricated.
-    }
-    this._changedFiles = [...files].sort();
-    return this._changedFiles;
-  }
-
-  isDocsTask() {
-    const files = this.getChangedFiles();
-    return files.length > 0 && files.every((file) => file.endsWith(".md") || file.endsWith(".txt") || file.startsWith("docs/"));
-  }
-
-  isUiTask() {
-    return this.getChangedFiles().some((file) =>
-      /\.(tsx|jsx|vue|html|css|scss|less|blade\.php)$/.test(file) ||
-      /(^|\/)(components|pages|views)\//.test(file)
-    );
-  }
-
-  isImplementationTask() {
-    const files = this.getChangedFiles();
-    if (files.length === 0 || this.isDocsTask()) return false;
-    return files.some((file) =>
-      file === "package.json" ||
-      /^(src|app|pages|components|server|api)\//.test(file) ||
-      /\.(js|jsx|ts|tsx|vue|php|py|rb|go|java|css|scss|html)$/.test(file)
-    );
-  }
-
-
-  async hasExecutableBehaviorChanges() {
-    const files = this.getChangedFiles().filter((file) => !isManagedChangePath(file));
-    const executableExtensions = /\.(js|jsx|mjs|cjs|ts|tsx|vue|php|py|rb|go|java|cs|rs|swift|kt|kts|sh|bash)$/i;
-    if (files.some((file) => executableExtensions.test(file))) return true;
-
-    for (const file of files.filter((item) => /\.(html?|xhtml)$/i.test(item))) {
-      try {
-        const content = await fs.readFile(path.join(this.cwd, file), "utf8");
-        if (/<script\b|\son(?:click|change|input|submit|keydown|keyup|load|error)\s*=|javascript:/i.test(content)) return true;
-      } catch {
-        // Missing or unreadable changed files are handled by the normal validation path.
-      }
-    }
-    return false;
-  }
-
-  verifyBranchSafety() {
-    const branch = this.getCurrentBranch();
-    const implementation = this.isImplementationTask();
-    if (!this.hasGitHead()) {
-      return { status: "PASS_WITH_NOTES", branch, reason: "Git HEAD unavailable; branch safety could not be verified." };
-    }
-    if (implementation && PROTECTED_BRANCHES.has(branch)) {
-      return { status: "FAIL_QUALITY_GATE", branch, reason: `Implementation changes are present on protected branch '${branch}'.` };
-    }
-    if (this.mode === "full") {
-      const mergeGate = new MergeGate({ cwd: this.cwd });
-      const mergeResult = mergeGate.check(branch);
-      if (mergeResult.status === "FAIL_QUALITY_GATE") {
-        return { status: "FAIL_QUALITY_GATE", branch, reason: mergeResult.reason };
-      }
-    }
-    return { status: "PASS", branch };
-  }
-
-  async verifyDocumentationNeed() {
-    if (!this.isImplementationTask()) return { status: "NOT_RUN", reason: "No implementation changes detected." };
-    const files = this.getChangedFiles();
-    const docsChanged = files.some((file) => file === "README.md" || file.startsWith("docs/") || file.endsWith(".md"));
-    const publicSurfaceChanged = files.some((file) =>
-      file === "package.json" ||
-      /(^|\/)(routes?|api|cli|commands?|config|public)\//.test(file) ||
-      /README|CHANGELOG/.test(file)
-    );
-    if (publicSurfaceChanged && !docsChanged) {
-      return { status: "PASS_WITH_NOTES", reason: "Public behavior may have changed without a documentation update." };
-    }
-    return { status: "PASS" };
-  }
-
-  async verifyUiEvidence() {
-    if (!this.isUiTask()) return { status: "NOT_RUN", reason: "Non-UI task." };
-    const candidates = ["docs", "screenshots", "evidence"];
-    const found = [];
-    for (const dir of candidates) {
-      const root = path.join(this.cwd, dir);
-      if (!(await exists(root))) continue;
-      const entries = await fs.readdir(root, { recursive: true }).catch(() => []);
-      for (const entry of entries) {
-        if (/\.(png|jpe?g|webp)$/i.test(String(entry))) found.push(normalizePath(path.join(dir, String(entry))));
-      }
-    }
-    return found.length
-      ? { status: "PASS", screenshots: found.slice(0, 20) }
-      : { status: "PASS_WITH_NOTES", reason: "UI changed without persisted screenshots; rely on the stated browser/manual review only if it actually occurred." };
-  }
-
-  async verifyFullModeEvidence() {
-    if (this.mode !== "full") return { status: "NOT_RUN", reason: "Persisted evidence is optional outside full mode." };
-    if (this.evidenceWillBePersisted) return { status: "PASS", reason: "Collector will persist observed full-mode evidence." };
-    const candidates = [
-      path.join(this.cwd, "EVIDENCE.json"),
-      this.taskSlug ? path.join(this.cwd, "docs/workflows", this.taskSlug, "evidence.json") : null
-    ].filter(Boolean);
-    for (const file of candidates) {
-      if (await exists(file)) return { status: "PASS", file: path.relative(this.cwd, file) };
-    }
-    return { status: "FAIL_QUALITY_GATE", reason: "Full mode requires persisted evidence generated from observed execution." };
-  }
-
-  verifyTruthfulnessBoundary() {
-    if (!this.isUiTask()) return { status: "NOT_RUN", reason: "Non-UI task." };
-    return {
-      status: "NOT_RUN",
-      reason: "Product truthfulness requires semantic review; keyword matching is intentionally not used as proof."
-    };
-  }
-
-  async verify() {
-    const branchSafety = this.verifyBranchSafety();
-    const documentation = await this.verifyDocumentationNeed();
-    const uiEvidence = await this.verifyUiEvidence();
-    const fullModeEvidence = await this.verifyFullModeEvidence();
-    const productTruthfulness = this.verifyTruthfulnessBoundary();
-
-    // productTruthfulness is intentionally excluded from the blocking checks array.
-    // Semantic truthfulness cannot be verified by keyword matching; it always returns
-    // NOT_RUN by design. It appears in the output as an observational signal for
-    // human reviewers, but never affects overallStatus.
-    const checks = [branchSafety, documentation, uiEvidence, fullModeEvidence];
-    let overallStatus = "PASS";
-    if (checks.some((check) => ["FAIL", "FAIL_QUALITY_GATE", "BLOCKED"].includes(check.status))) {
-      overallStatus = "FAIL_QUALITY_GATE";
-    } else if (checks.some((check) => check.status === "PASS_WITH_NOTES")) {
-      overallStatus = "PASS_WITH_NOTES";
-    }
-
-    return {
-      overallStatus,
-      isUiTask: this.isUiTask(),
-      isDocsTask: this.isDocsTask(),
-      isImplementationTask: this.isImplementationTask(),
-      git: {
-        hasHead: this.hasGitHead(),
-        branch: this.getCurrentBranch(),
-        changedFiles: this.getChangedFiles()
-      },
-      checks: {
-        branchSafety,
-        documentation,
-        uiEvidence,
-        fullModeEvidence,
-        productTruthfulness
-      }
-    };
-  }
-}

package/src/core/validation/stack-detector.js

@@ -1,65 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-
-export class StackDetector {
-  constructor({ cwd = process.cwd() } = {}) {
-    this.cwd = cwd;
-  }
-
-  async detect() {
-    const stacks = [];
-
-    // 1. Node check
-    const packageJsonExists = await fs.access(path.join(this.cwd, "package.json")).then(() => true).catch(() => false);
-    if (packageJsonExists) {
-      stacks.push("node");
-    }
-
-    // 2. Python check
-    const pyprojectExists = await fs.access(path.join(this.cwd, "pyproject.toml")).then(() => true).catch(() => false) ||
-                             await fs.access(path.join(this.cwd, "requirements.txt")).then(() => true).catch(() => false) ||
-                             await fs.access(path.join(this.cwd, "setup.py")).then(() => true).catch(() => false) ||
-                             await fs.access(path.join(this.cwd, "Pipfile")).then(() => true).catch(() => false);
-    
-    let hasPythonFiles = pyprojectExists;
-    if (!hasPythonFiles) {
-      hasPythonFiles = await this.hasFileWithExtension(this.cwd, ".py");
-    }
-    if (hasPythonFiles) {
-      stacks.push("python");
-    }
-
-    // 3. PHP check
-    const composerExists = await fs.access(path.join(this.cwd, "composer.json")).then(() => true).catch(() => false);
-    let hasPhpFiles = composerExists;
-    if (!hasPhpFiles) {
-      hasPhpFiles = await this.hasFileWithExtension(this.cwd, ".php");
-    }
-    if (hasPhpFiles) {
-      stacks.push("php");
-    }
-
-    return stacks;
-  }
-
-  async hasFileWithExtension(dir, ext) {
-    try {
-      const entries = await fs.readdir(dir, { withFileTypes: true });
-      for (const entry of entries) {
-        if (entry.isDirectory()) {
-          if (["node_modules", "vendor", ".git", "dist", "build", ".cache"].includes(entry.name)) {
-            continue;
-          }
-          const subPath = path.join(dir, entry.name);
-          const found = await this.hasFileWithExtension(subPath, ext);
-          if (found) return true;
-        } else if (entry.isFile() && entry.name.endsWith(ext)) {
-          return true;
-        }
-      }
-    } catch {
-      // ignore
-    }
-    return false;
-  }
-}

package/src/core/validation/validation-planner.js

@@ -1,134 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { StackDetector } from "./stack-detector.js";
-
-export class ValidationPlanner {
-  constructor({ cwd = process.cwd(), qualityGuard } = {}) {
-    this.cwd = cwd;
-    this.qualityGuard = qualityGuard;
-    this.stackDetector = new StackDetector({ cwd });
-  }
-
-  async plan(profile = "generic") {
-    const stacks = await this.stackDetector.detect();
-    const tasks = [];
-
-    const changedFiles = this.qualityGuard.getChangedFiles().filter((file) => {
-      return !/(^|\/)(node_modules|vendor|dist|coverage|\.cache)(\/|$)/.test(String(file).replaceAll("\\", "/"));
-    });
-    const executableBehavior = await this.qualityGuard.hasExecutableBehaviorChanges();
-
-    // Node Stack Planning
-    if (stacks.includes("node")) {
-      try {
-        const pkg = JSON.parse(await fs.readFile(path.join(this.cwd, "package.json"), "utf8"));
-        const scripts = pkg.scripts || {};
-
-        this.addNodeScriptTask(tasks, scripts, "lint", ["npm", "run", "lint"]);
-        this.addNodeScriptTask(tasks, scripts, "test", ["npm", "test"], { rejectNoOp: executableBehavior });
-        this.addNodeScriptTask(tasks, scripts, "build", ["npm", "run", "build"]);
-        this.addNodeScriptTask(tasks, scripts, "typecheck", ["npm", "run", "typecheck"]);
-
-        if (scripts.validate && !String(scripts.validate).includes("ai-workflow collect-evidence")) {
-          this.addNodeScriptTask(tasks, scripts, "validate", ["npm", "run", "validate"]);
-        }
-
-        const hasTs = changedFiles.some((file) => /\.(ts|tsx)$/.test(file)) ||
-                      await fs.access(path.join(this.cwd, "tsconfig.json")).then(() => true).catch(() => false);
-        if (hasTs && !scripts.typecheck) {
-          tasks.push({
-            name: "typecheck",
-            command: ["npm", "run", "typecheck"],
-            kind: "typecheck",
-            presetStatus: "FAIL_QUALITY_GATE",
-            summary: "TypeScript detected but no typecheck script is configured."
-          });
-        }
-      } catch {
-        // Fallback or ignore if pkg read fails
-      }
-    }
-
-    // Python Stack Planning
-    if (stacks.includes("python")) {
-      const pythonFiles = changedFiles.filter(f => f.endsWith(".py"));
-
-      // Compiler syntax check for changed python files
-      if (pythonFiles.length > 0) {
-        tasks.push({
-          name: "python-syntax",
-          command: ["python", "-m", "py_compile", ...pythonFiles],
-          kind: "lint"
-        });
-      }
-
-      // Check if testing is needed
-      if (executableBehavior) {
-        // Check if pytest or unittest is configured
-        const hasPytestConfig = await fs.access(path.join(this.cwd, "pytest.ini")).then(() => true).catch(() => false) ||
-                                await fs.access(path.join(this.cwd, "pyproject.toml")).then(() => true).catch(() => false);
-        
-        if (hasPytestConfig || pythonFiles.length > 0) {
-          tasks.push({
-            name: "python-test",
-            command: ["pytest"],
-            kind: "test"
-          });
-        }
-      }
-    }
-
-    // PHP Stack Planning
-    if (stacks.includes("php")) {
-      const phpFiles = changedFiles.filter(f => f.endsWith(".php") || f.endsWith(".inc"));
-
-      // Compiler syntax check for each changed PHP file - split into separate tasks
-      if (phpFiles.length > 0) {
-        for (const file of phpFiles) {
-          tasks.push({
-            name: `php-syntax:${file}`,
-            command: ["php", "-l", file],
-            kind: "lint"
-          });
-        }
-      }
-
-      // Check if testing is needed
-      if (executableBehavior) {
-        const hasPhpUnitXml = await fs.access(path.join(this.cwd, "phpunit.xml")).then(() => true).catch(() => false) ||
-                              await fs.access(path.join(this.cwd, "phpunit.xml.dist")).then(() => true).catch(() => false);
-        if (hasPhpUnitXml || phpFiles.length > 0) {
-          tasks.push({
-            name: "php-test",
-            command: ["vendor/bin/phpunit"],
-            kind: "test"
-          });
-        }
-      }
-    }
-
-    return tasks;
-  }
-
-  addNodeScriptTask(tasks, scripts, name, command, { rejectNoOp = false } = {}) {
-    const script = scripts[name];
-    if (!script) return;
-    if (!rejectNoOp && name === "test" && this.isNoOpScript(script)) return;
-    if (rejectNoOp && this.isNoOpScript(script)) {
-      tasks.push({
-        name,
-        command,
-        kind: name === "test" ? "test" : name,
-        presetStatus: "FAIL_QUALITY_GATE",
-        summary: `Configured ${name} script is a no-op: ${script}`
-      });
-      return;
-    }
-    tasks.push({ name, command, kind: name === "test" ? "test" : name });
-  }
-
-  isNoOpScript(script = "") {
-    const value = String(script).trim().toLowerCase();
-    return /^(echo\b|true$|exit\s+0$|node\s+-e\s+["']?console\.log)/.test(value) || value.includes("tests-pass");
-  }
-}

package/src/core/validation/visual-verifier.js

@@ -1,175 +0,0 @@
-import http from "node:http";
-import fs from "node:fs/promises";
-import path from "node:path";
-
-export class VisualVerifier {
-  constructor({ cwd = process.cwd(), visualDist = null, port = 8080 } = {}) {
-    this.cwd = cwd;
-    this.visualDist = visualDist;
-    this.port = Number(port || 8080);
-    this.server = null;
-  }
-
-  async startServer() {
-    if (!this.visualDist) {
-      throw new Error("No --visual-dist directory specified. Cannot start visual server.");
-    }
-    const distPath = path.resolve(this.cwd, this.visualDist);
-    this.server = http.createServer(async (req, res) => {
-      try {
-        const urlPath = req.url.split("?")[0];
-        const filePath = path.join(distPath, urlPath === "/" ? "index.html" : urlPath);
-        const content = await fs.readFile(filePath);
-        
-        const ext = path.extname(filePath).toLowerCase();
-        let contentType = "text/html";
-        if (ext === ".js" || ext === ".mjs") contentType = "application/javascript";
-        else if (ext === ".css") contentType = "text/css";
-        else if (ext === ".png") contentType = "image/png";
-        else if (ext === ".jpg" || ext === ".jpeg") contentType = "image/jpeg";
-        else if (ext === ".svg") contentType = "image/svg+xml";
-        
-        res.writeHead(200, { "Content-Type": contentType });
-        res.end(content);
-      } catch (err) {
-        res.writeHead(404, { "Content-Type": "text/plain" });
-        res.end("Not Found");
-      }
-    });
-
-    await new Promise((resolve, reject) => {
-      this.server.listen(this.port, "127.0.0.1", (err) => {
-        if (err) reject(err);
-        else resolve();
-      });
-    });
-  }
-
-  async closeServer() {
-    if (this.server) {
-      await new Promise((resolve) => this.server.close(resolve));
-      this.server = null;
-    }
-  }
-
-  async captureScreenshots() {
-    if (!this.visualDist) return [];
-
-    let playwright;
-    try {
-      playwright = await import("playwright");
-    } catch {
-      throw new Error(
-        "Playwright is required to capture visual evidence. Please install it using 'npm install -D playwright' and initialize browsers using 'npx playwright install'."
-      );
-    }
-
-    await this.startServer();
-    let browser;
-    try {
-      browser = await playwright.chromium.launch();
-    } catch (err) {
-      await this.closeServer();
-      throw new Error(
-        `Failed to launch Playwright Chromium. Please ensure browsers are installed using 'npx playwright install chromium'. Details: ${err.message}`
-      );
-    }
-    const page = await browser.newPage();
-
-    const outputDir = path.join(this.cwd, ".evidence/visual");
-    await fs.mkdir(outputDir, { recursive: true });
-
-    const desktopPath = path.join(outputDir, "desktop.png");
-    const mobilePath = path.join(outputDir, "mobile.png");
-
-    try {
-      await page.goto(`http://127.0.0.1:${this.port}`);
-
-      // Desktop
-      await page.setViewportSize({ width: 1440, height: 900 });
-      await page.screenshot({ path: desktopPath, fullPage: true });
-
-      // Mobile
-      await page.setViewportSize({ width: 390, height: 844 });
-      await page.screenshot({ path: mobilePath, fullPage: true });
-    } finally {
-      await browser.close();
-      await this.closeServer();
-    }
-
-    return [desktopPath, mobilePath];
-  }
-
-  async runAccessibilityCheck() {
-    if (!this.visualDist) {
-      throw new Error("Accessibility check requires a target build directory specified via --visual-dist.");
-    }
-
-    let playwright;
-    try {
-      playwright = await import("playwright");
-    } catch {
-      throw new Error(
-        "Playwright is required to run accessibility checks. Please install it using 'npm install -D playwright' and initialize browsers using 'npx playwright install'."
-      );
-    }
-
-    await this.startServer();
-    let browser;
-    try {
-      browser = await playwright.chromium.launch();
-    } catch (err) {
-      await this.closeServer();
-      throw new Error(
-        `Failed to launch Playwright Chromium. Please ensure browsers are installed using 'npx playwright install chromium'. Details: ${err.message}`
-      );
-    }
-    const page = await browser.newPage();
-
-    const outputDir = path.join(this.cwd, ".evidence/a11y");
-    await fs.mkdir(outputDir, { recursive: true });
-
-    try {
-      await page.goto(`http://127.0.0.1:${this.port}`);
-
-      // Read axe-core bundle
-      let axeScript = "";
-      try {
-        const axePath = path.join(this.cwd, "node_modules/axe-core/axe.min.js");
-        axeScript = await fs.readFile(axePath, "utf8");
-      } catch {
-        // Fallback: look in dev-kit node_modules
-        try {
-          // Resolve relative to current module path
-          const mainAxePath = path.resolve(path.dirname(new URL(import.meta.url).pathname), "../../../node_modules/axe-core/axe.min.js");
-          axeScript = await fs.readFile(mainAxePath, "utf8");
-        } catch {
-          throw new Error("axe-core package is not installed. Please install axe-core using 'npm install -D axe-core'.");
-        }
-      }
-
-      await page.evaluate(axeScript);
-
-      const axeResults = await page.evaluate(() => {
-        return window.axe.run();
-      });
-
-      const reportPath = path.join(outputDir, "report.json");
-      await fs.writeFile(reportPath, JSON.stringify(axeResults, null, 2));
-
-      const criticalViolations = axeResults.violations.filter(v => v.impact === "critical");
-      const seriousViolations = axeResults.violations.filter(v => v.impact === "serious");
-
-      return {
-        passed: criticalViolations.length === 0,
-        reportPath,
-        violations: axeResults.violations,
-        critical: criticalViolations,
-        serious: seriousViolations
-      };
-    } finally {
-      await browser.close();
-      await this.closeServer();
-    }
-  }
-}