@qatonic_innovations/qaios 0.5.2 → 0.6.0

package/dist/a11y-X3GULPJY.js

@@ -0,0 +1,355 @@
+#!/usr/bin/env node
+import { resolveLlmClient, llmKeyCheck, warnAiSkipped, auditA11ySkill, defectCreateSkill } from './chunk-RQP7ALWK.js';
+import './chunk-VSSX6F42.js';
+import { getQaiosVersion } from './chunk-RDZE7TZG.js';
+import { loadCommandConfig } from './chunk-ICKV4DDG.js';
+import { ExitCode } from './chunk-EAMUH7ZB.js';
+import { loadProjectMemory, Storage, AuditLogger, WorkflowsRepository, runAxe, AxeRunError, ArtifactsRepository, SkillRunner, McpServersRepository, McpClient, fileDefect } from './chunk-XKBSTVSC.js';
+import { ulid } from './chunk-3SEEYC6R.js';
+import { createHash } from 'crypto';
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import path from 'path';
+
+var GLYPH = { ok: "\u2713", failed: "\u2717", warn: "\u26A0", issue: "\u2691" };
+var MAX_TARGETS_SHOWN = 3;
+function formatRawFinding(f) {
+  const lines = [`  ${GLYPH.issue} [${f.kind}/${f.impact ?? "unknown"}] ${f.id}: ${f.description}`];
+  const targets = f.nodes.map((n) => n.target.join(" "));
+  if (targets.length > 0) {
+    const shown = targets.slice(0, MAX_TARGETS_SHOWN).join(", ");
+    const more = targets.length > MAX_TARGETS_SHOWN ? ` (+${targets.length - MAX_TARGETS_SHOWN} more)` : "";
+    const noun = targets.length === 1 ? "element" : "elements";
+    lines.push(`      ${targets.length} ${noun}: ${shown}${more}`);
+  }
+  if (f.helpUrl.length > 0) lines.push(`      ${f.helpUrl}`);
+  return lines;
+}
+async function runA11y(opts) {
+  const cwd = path.resolve(opts.cwd ?? process.cwd());
+  if (!opts.url || opts.url.trim().length === 0) {
+    return {
+      exitCode: ExitCode.USER_ERROR,
+      error: {
+        code: "qaios.a11y.no_url",
+        message: "must provide a URL to scan (positional argument)."
+      }
+    };
+  }
+  const qaiosDir = path.join(cwd, ".qaios");
+  if (!existsSync(qaiosDir) && opts.storage === void 0) {
+    return {
+      exitCode: ExitCode.USER_ERROR,
+      error: {
+        code: "qaios.a11y.not_initialized",
+        message: `${cwd} is not a QAIOS project \u2014 run \`qaios init\` first.`
+      }
+    };
+  }
+  const config = loadCommandConfig(cwd, opts.configSelection);
+  const memory = loadProjectMemory(cwd);
+  const mode = opts.mode ?? config?.mode ?? "LITE";
+  const wcagLevel = opts.wcagLevel ?? "AA";
+  const ownsStorage = opts.storage === void 0;
+  const storage = opts.storage ?? Storage.open(path.join(qaiosDir, "workflows.db"), { skipMigrations: false });
+  const auditLogger = new AuditLogger(storage.db);
+  const workflowsRepo = new WorkflowsRepository(storage.db);
+  const llm = resolveLlmClient(opts.llm, config?.llm);
+  const writeOut = (line) => {
+    if (opts.quiet === true) return;
+    if (opts.json === true) process.stdout.write(JSON.stringify({ kind: "log", line }) + "\n");
+    else process.stdout.write(line + "\n");
+  };
+  const finalize = (workflowId, status) => {
+    workflowsRepo.update(workflowId, { status, finishedAt: (/* @__PURE__ */ new Date()).toISOString() });
+    auditLogger.append({
+      workflowId,
+      phase: "ORCHESTRATION",
+      skillId: null,
+      event: status === "succeeded" ? "workflow.completed" : "workflow.failed",
+      payload: {},
+      actor: "system"
+    });
+  };
+  try {
+    const workflowId = ulid();
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const args = { url: opts.url, wcagLevel, noDefects: opts.noDefects === true };
+    workflowsRepo.create({
+      id: workflowId,
+      command: "a11y",
+      args,
+      state: "running",
+      mode,
+      status: "running",
+      blockedReason: null,
+      cost: { tokens: 0, usdCents: 0 },
+      createdAt: now,
+      updatedAt: now,
+      finishedAt: null
+    });
+    auditLogger.append({
+      workflowId,
+      phase: "ORCHESTRATION",
+      skillId: null,
+      event: "workflow.created",
+      payload: { command: "a11y", mode, args },
+      actor: "system"
+    });
+    writeOut(`workflow: ${workflowId}`);
+    writeOut("");
+    writeOut(
+      `Running axe-core accessibility scan (${opts.tags !== void 0 ? `axe tags: ${opts.tags.join(", ")}` : `WCAG ${wcagLevel}`})...`
+    );
+    const runAxeFn = opts.runAxe ?? runAxe;
+    const tags = opts.tags ?? wcagTagsFor(wcagLevel);
+    let findings;
+    let redirect;
+    try {
+      findings = await runAxeFn({
+        url: opts.url,
+        cwd,
+        tags,
+        onRedirect: (finalUrl) => {
+          redirect = finalUrl;
+        }
+      });
+      if (redirect !== void 0) {
+        writeOut(
+          `  ${GLYPH.warn} ${opts.url} redirected to ${redirect}; the scan covers that page. A page behind a login cannot be scanned directly yet.`
+        );
+      }
+    } catch (err) {
+      const code = err instanceof AxeRunError ? err.code : "qaios.a11y.scan_failed";
+      const message = err.message ?? String(err);
+      finalize(workflowId, "failed");
+      writeOut(`${GLYPH.failed} ${code}: ${message}`);
+      return { exitCode: ExitCode.TOOL_ERROR, workflowId, error: { code, message } };
+    }
+    const violationCount = findings.filter((f) => f.kind === "violation").length;
+    const incompleteCount = findings.filter((f) => f.kind === "incomplete").length;
+    const bestPracticeCount = findings.filter((f) => f.kind === "best_practice").length;
+    writeOut(
+      `  ${GLYPH.ok} scan complete \u2014 ${violationCount} violation(s), ${incompleteCount} needs-review, ${bestPracticeCount} best-practice`
+    );
+    writeOut("");
+    const specsDir = path.join(qaiosDir, "specs", workflowId);
+    const writeReport = (report) => {
+      mkdirSync(specsDir, { recursive: true });
+      const text = JSON.stringify(report, null, 2) + "\n";
+      writeFileSync(path.join(specsDir, "A11yReport.json"), text);
+      new ArtifactsRepository(storage.db).recordOnce({
+        workflowId,
+        skillId: "audit.a11y",
+        type: "A11yReport",
+        path: `.qaios/specs/${workflowId}/A11yReport.json`,
+        contentHash: createHash("sha256").update(text).digest("hex"),
+        confidence: 1
+      });
+    };
+    if (findings.length === 0) {
+      writeReport({ url: opts.url, wcagLevel, findings: [], issues: [] });
+      writeOut("No accessibility issues found.");
+      finalize(workflowId, "succeeded");
+      return {
+        exitCode: ExitCode.SUCCESS,
+        workflowId,
+        issues: [],
+        findings: [],
+        findingCount: 0,
+        violationCount: 0,
+        defectsFiled: 0
+      };
+    }
+    const skillInput = {
+      url: opts.url,
+      wcagLevel,
+      findings: findings.map((f) => ({
+        kind: f.kind,
+        id: f.id,
+        impact: f.impact ?? null,
+        description: f.description,
+        help: f.help,
+        helpUrl: f.helpUrl,
+        tags: f.tags,
+        nodes: f.nodes.map((n) => ({
+          html: n.html,
+          target: n.target,
+          failureSummary: n.failureSummary
+        }))
+      }))
+    };
+    const skillCtx = {
+      workflowId,
+      projectMemory: "",
+      prior: {},
+      auditLogger,
+      llm,
+      ...opts.cancelSignal !== void 0 ? { cancelSignal: opts.cancelSignal } : {},
+      ...memory !== null ? { qaiosMemoryFull: memory } : {}
+    };
+    let triaged = null;
+    const keyCheck = llmKeyCheck(opts.llm, config?.llm);
+    if (!keyCheck.ok) {
+      if (opts.quiet !== true) warnAiSkipped(keyCheck);
+    } else {
+      writeOut("Triaging findings (priority + WCAG mapping + remediation)...");
+      try {
+        const result = await new SkillRunner().run(auditA11ySkill, skillCtx, skillInput);
+        triaged = result.output;
+      } catch (err) {
+        writeOut(
+          `  ${GLYPH.warn} triage failed (${err.message}); reporting raw axe findings.`
+        );
+      }
+    }
+    const issues = triaged?.issues ?? [];
+    writeReport({ url: opts.url, wcagLevel, findings, issues });
+    writeOut("");
+    const violations = issues.filter((i) => i.kind === "violation");
+    const needsReview = issues.filter((i) => i.kind === "incomplete");
+    const bestPractice = issues.filter((i) => i.kind === "best_practice");
+    if (triaged !== null) {
+      if (violations.length > 0) {
+        writeOut(`Violations (${violations.length}) \u2014 must fix:`);
+        for (const it of violations) {
+          writeOut(`  ${GLYPH.issue} [${it.priority.toUpperCase()}] ${it.title} (${it.ruleId})`);
+        }
+      }
+      if (needsReview.length > 0) {
+        writeOut(`Needs manual review (${needsReview.length}) \u2014 axe couldn't be certain:`);
+        for (const it of needsReview) {
+          writeOut(`  ${GLYPH.warn} ${it.title} (${it.ruleId})`);
+        }
+      }
+      if (bestPractice.length > 0) {
+        writeOut(`Best practices (${bestPractice.length}) \u2014 recommendations:`);
+        for (const it of bestPractice) {
+          writeOut(`  \u2022 ${it.title} (${it.ruleId})`);
+        }
+      }
+    } else {
+      for (const f of findings) for (const line of formatRawFinding(f)) writeOut(line);
+    }
+    writeOut("");
+    let defectsFiled = 0;
+    if (opts.noDefects !== true && violations.length > 0) {
+      const target = opts.defectTarget ?? config?.defects?.target ?? "stdout";
+      const repo = opts.defectRepo ?? config?.defects?.repo;
+      const project = opts.defectProject ?? config?.defects?.project;
+      writeOut(`Filing ${violations.length} violation defect(s) (target: ${target})...`);
+      let mcpClient = opts.mcpClient;
+      if (target !== "stdout" && mcpClient === void 0) {
+        const repoMcp = new McpServersRepository(storage.db);
+        const servers = repoMcp.list();
+        mcpClient = new McpClient({
+          servers,
+          auditLogger,
+          workflowId,
+          clientVersion: getQaiosVersion()
+        });
+      }
+      for (const issue of violations) {
+        const filed = await fileIssueAsDefect({
+          issue,
+          url: opts.url,
+          workflowId,
+          target,
+          repo,
+          project,
+          mcpClient,
+          llm,
+          auditLogger,
+          memory
+        });
+        if (filed.success) {
+          defectsFiled++;
+          const urlSuffix = filed.url !== void 0 ? ` \u2192 ${filed.url}` : "";
+          writeOut(`  ${GLYPH.ok} ${filed.id ?? "filed"}: ${issue.title}${urlSuffix}`);
+        } else {
+          writeOut(`  ${GLYPH.failed} ${issue.title} \u2014 ${filed.error ?? "unknown failure"}`);
+        }
+      }
+      if (mcpClient !== void 0 && opts.mcpClient === void 0) await mcpClient.close();
+    }
+    finalize(workflowId, "succeeded");
+    return {
+      exitCode: violationCount > 0 ? ExitCode.USER_ERROR : ExitCode.SUCCESS,
+      workflowId,
+      issues,
+      findings,
+      findingCount: findings.length,
+      violationCount,
+      defectsFiled
+    };
+  } finally {
+    if (ownsStorage) storage.close();
+  }
+}
+function wcagTagsFor(level) {
+  if (level === "A") return ["wcag2a", "wcag21a"];
+  if (level === "AAA") return ["wcag2a", "wcag2aa", "wcag2aaa", "wcag21a", "wcag21aa"];
+  return ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"];
+}
+async function fileIssueAsDefect(args) {
+  const i = args.issue;
+  const wcag = i.wcagCriterion !== void 0 ? ` (WCAG ${i.wcagCriterion})` : "";
+  const skillInput = {
+    source: "exploratory_finding",
+    context: {
+      workflowId: args.workflowId,
+      requirementIds: [],
+      findingDescription: `Accessibility: ${i.title}${wcag} [axe rule: ${i.ruleId}]`,
+      reproSteps: [
+        `Run an accessibility scan (axe-core) against ${args.url}.`,
+        `Inspect the element(s): ${i.affectedSelectors.slice(0, 5).join(", ") || "(see report)"}.`
+      ],
+      expectedBehavior: `The page conforms to the relevant WCAG${wcag} success criterion.`,
+      actualBehavior: `axe-core rule \`${i.ruleId}\` (impact: ${i.axeImpact}) fails. ${i.remediation}`,
+      severity: i.priority,
+      attachments: [],
+      environment: { url: args.url }
+    },
+    target: {
+      integration: args.target,
+      ...args.repo !== void 0 ? { repo: args.repo } : {},
+      ...args.project !== void 0 ? { project: args.project } : {},
+      labels: ["accessibility", "a11y"]
+    }
+  };
+  const ctx = {
+    workflowId: args.workflowId,
+    projectMemory: "",
+    prior: {},
+    auditLogger: args.auditLogger,
+    llm: args.llm,
+    ...args.memory !== null ? { qaiosMemoryFull: args.memory } : {}
+  };
+  let defectOutput;
+  try {
+    const result = await new SkillRunner().run(defectCreateSkill, ctx, skillInput);
+    defectOutput = result.output;
+  } catch (err) {
+    return { success: false, error: err.message };
+  }
+  const rule = `[axe rule: ${i.ruleId}]`;
+  const defect = defectOutput.defect.title.includes(rule) ? defectOutput.defect : { ...defectOutput.defect, title: `${defectOutput.defect.title} ${rule}` };
+  const filed = await fileDefect({
+    defect,
+    target: {
+      integration: args.target,
+      ...args.repo !== void 0 ? { repo: args.repo } : {},
+      ...args.project !== void 0 ? { project: args.project } : {}
+    },
+    ...args.mcpClient !== void 0 ? { mcpClient: args.mcpClient } : {},
+    auditLogger: args.auditLogger,
+    workflowId: args.workflowId
+  });
+  return {
+    success: filed.success,
+    ...filed.id !== void 0 ? { id: filed.id } : {},
+    ...filed.url !== void 0 ? { url: filed.url } : {},
+    ...filed.error !== void 0 ? { error: filed.error } : {}
+  };
+}
+
+export { formatRawFinding, runA11y };