@vertaaux/cli 0.2.0

package/dist/policy/schema.js

@@ -0,0 +1,230 @@
+/**
+ * Policy file schema for vertaa.policy.yml.
+ *
+ * Enables policy-as-code for organizations to define:
+ * - Quality thresholds and assertions
+ * - Rule severity overrides
+ * - Branch-specific policies
+ * - Bypass labels for emergency deploys
+ *
+ * Modeled on Semgrep/ESLint policy patterns.
+ *
+ * Implements CICD-17: Policy-as-code support.
+ */
+/**
+ * JSON Schema for vertaa.policy.yml validation.
+ *
+ * Used for:
+ * - Runtime validation with Ajv
+ * - IDE autocompletion and validation
+ * - Documentation generation
+ */
+export const policyJsonSchema = {
+    $schema: "http://json-schema.org/draft-07/schema#",
+    $id: "https://vertaaux.ai/schemas/policy.json",
+    title: "VertaaUX Policy",
+    description: "Policy-as-code configuration for VertaaUX quality gates. Commit this file to your repository to define organization-wide UX standards.",
+    type: "object",
+    properties: {
+        $schema: {
+            type: "string",
+            description: "JSON Schema reference for IDE support",
+        },
+        version: {
+            type: "number",
+            enum: [1],
+            description: "Policy file format version (currently only version 1)",
+        },
+        name: {
+            type: "string",
+            description: "Human-readable policy name",
+        },
+        description: {
+            type: "string",
+            description: "Policy description for documentation",
+        },
+        assertions: {
+            type: "object",
+            description: "Threshold assertions that must pass",
+            properties: {
+                overall_score: {
+                    type: "number",
+                    minimum: 0,
+                    maximum: 100,
+                    description: "Minimum overall score (0-100)",
+                },
+                accessibility_score: {
+                    type: "number",
+                    minimum: 0,
+                    maximum: 100,
+                    description: "Minimum accessibility score (0-100)",
+                },
+                ux_score: {
+                    type: "number",
+                    minimum: 0,
+                    maximum: 100,
+                    description: "Minimum UX score (0-100)",
+                },
+                performance_score: {
+                    type: "number",
+                    minimum: 0,
+                    maximum: 100,
+                    description: "Minimum performance score (0-100)",
+                },
+                fail_on: {
+                    type: "string",
+                    enum: ["error", "warning", "info"],
+                    description: "Fail on issues at or above this severity",
+                },
+                max_new_errors: {
+                    type: "number",
+                    minimum: 0,
+                    description: "Maximum new error-severity issues allowed",
+                },
+                max_new_warnings: {
+                    type: "number",
+                    minimum: 0,
+                    description: "Maximum new warning-severity issues allowed",
+                },
+                max_new_total: {
+                    type: "number",
+                    minimum: 0,
+                    description: "Maximum total new issues allowed",
+                },
+            },
+            additionalProperties: false,
+        },
+        rules: {
+            type: "object",
+            description: "Rule-specific severity overrides",
+            additionalProperties: {
+                type: "object",
+                properties: {
+                    severity: {
+                        type: "string",
+                        enum: ["error", "warning", "info", "ignore"],
+                        description: "Override severity for this rule",
+                    },
+                    reason: {
+                        type: "string",
+                        description: "Reason for override (for audit trail)",
+                    },
+                    paths: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Apply override only to these paths (glob patterns)",
+                    },
+                },
+                required: ["severity"],
+                additionalProperties: false,
+            },
+        },
+        branches: {
+            type: "object",
+            description: "Branch-specific policy overrides",
+            additionalProperties: {
+                type: "object",
+                properties: {
+                    pattern: {
+                        type: "string",
+                        description: "Branch pattern (glob). If not specified, uses exact match.",
+                    },
+                    assertions: {
+                        $ref: "#/properties/assertions",
+                        description: "Override assertions for this branch",
+                    },
+                },
+                additionalProperties: false,
+            },
+        },
+        bypass_labels: {
+            type: "array",
+            items: { type: "string" },
+            description: "PR labels that bypass quality gate entirely (e.g., emergency-fix)",
+        },
+        exclude_paths: {
+            type: "array",
+            items: { type: "string" },
+            description: "Path patterns to exclude from auditing",
+        },
+        required_version: {
+            type: "string",
+            description: "Required minimum CLI version (semver range, e.g., >=1.0.0)",
+        },
+    },
+    required: ["version", "assertions"],
+    additionalProperties: false,
+};
+/**
+ * Default policy with sensible enterprise defaults.
+ *
+ * - Only fail on errors (not warnings/info)
+ * - Only fail on NEW errors (existing debt allowed)
+ * - Common emergency bypass labels
+ */
+export const DEFAULT_POLICY = {
+    version: 1,
+    assertions: {
+        fail_on: "error",
+        max_new_errors: 0,
+    },
+    bypass_labels: ["skip-vertaa", "emergency-fix"],
+};
+/**
+ * Policy templates for different strictness levels.
+ */
+export const POLICY_TEMPLATES = {
+    /**
+     * Basic template - fail only on new errors.
+     */
+    basic: {
+        version: 1,
+        name: "Basic Policy",
+        description: "Block new error-severity issues only",
+        assertions: {
+            fail_on: "error",
+            max_new_errors: 0,
+        },
+        bypass_labels: ["skip-vertaa", "emergency-fix"],
+    },
+    /**
+     * Strict template - fail on warnings, require minimum scores.
+     */
+    strict: {
+        version: 1,
+        name: "Strict Policy",
+        description: "Maintain high quality standards with score thresholds and zero tolerance for new issues",
+        assertions: {
+            fail_on: "warning",
+            overall_score: 80,
+            max_new_errors: 0,
+            max_new_warnings: 0,
+        },
+        branches: {
+            main: {
+                assertions: {
+                    overall_score: 85,
+                },
+            },
+            "release/*": {
+                pattern: "release/*",
+                assertions: {
+                    overall_score: 90,
+                },
+            },
+        },
+        bypass_labels: ["emergency-fix"],
+    },
+    /**
+     * Lenient template - fail only on critical errors.
+     */
+    lenient: {
+        version: 1,
+        name: "Lenient Policy",
+        description: "Minimal quality gate for gradual adoption",
+        assertions: {
+            fail_on: "error",
+        },
+        bypass_labels: ["skip-vertaa", "emergency-fix", "wip"],
+    },
+};

package/dist/quality-gate/evaluator.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Quality gate evaluation for CI pipelines.
+ *
+ * Determines whether a CI build should pass or fail based on audit results.
+ * Key principle: Only fail on NEW issues, not existing technical debt.
+ *
+ * Implements:
+ * - CICD-06: Fail on new issues only
+ * - CICD-07: Threshold enforcement
+ * - CICD-13: Budget-aware evaluation
+ */
+import type { QualityGateConfig, QualityGateResult } from "./types.js";
+import type { BaselineFile } from "../baseline/manager.js";
+import type { Issue } from "../baseline/hash.js";
+/**
+ * Audit result type for quality gate evaluation.
+ */
+export interface AuditResultForGate {
+    /** Issues found during audit */
+    issues?: Issue[] | Record<string, Issue[]>;
+    /** Score breakdown */
+    scores?: Record<string, number | unknown>;
+    /** Any runtime error */
+    error?: unknown;
+}
+/**
+ * Options for quality gate evaluation.
+ */
+export interface EvaluateOptions {
+    /** Audit result with issues and scores */
+    auditResult: AuditResultForGate;
+    /** Baseline for comparison (optional - if missing, all issues treated as new) */
+    baseline?: BaselineFile | null;
+    /** Quality gate configuration */
+    config: QualityGateConfig;
+    /** PR labels for bypass check */
+    labels?: string[];
+}
+/**
+ * Evaluate quality gate based on audit results.
+ *
+ * Evaluation order:
+ * 1. Check bypass labels (short-circuit if matched)
+ * 2. Compute diff against baseline (new vs existing)
+ * 3. Count new issues by severity
+ * 4. Check thresholds against scores
+ * 5. Build violations list
+ * 6. Determine exit code
+ *
+ * @param options - Evaluation options
+ * @returns Quality gate result with pass/fail status and violations
+ */
+export declare function evaluateQualityGate(options: EvaluateOptions): QualityGateResult;
+/**
+ * Format quality gate result for human-readable output.
+ */
+export declare function formatQualityGateResult(result: QualityGateResult): string;
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/quality-gate/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../src/quality-gate/evaluator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAGjD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,gCAAgC;IAChC,MAAM,CAAC,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3C,sBAAsB;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;IAC1C,wBAAwB;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,0CAA0C;IAC1C,WAAW,EAAE,kBAAkB,CAAC;IAChC,iFAAiF;IACjF,QAAQ,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC/B,iCAAiC;IACjC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAiGD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,iBAAiB,CAmJ/E;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAyCzE"}

package/dist/quality-gate/evaluator.js

@@ -0,0 +1,274 @@
+/**
+ * Quality gate evaluation for CI pipelines.
+ *
+ * Determines whether a CI build should pass or fail based on audit results.
+ * Key principle: Only fail on NEW issues, not existing technical debt.
+ *
+ * Implements:
+ * - CICD-06: Fail on new issues only
+ * - CICD-07: Threshold enforcement
+ * - CICD-13: Budget-aware evaluation
+ */
+import { computeDiff } from "../baseline/diff.js";
+import { ExitCode } from "../utils/exit-codes.js";
+/** Severity ranking for comparison */
+const SEVERITY_RANK = {
+    error: 3,
+    critical: 3,
+    warning: 2,
+    serious: 2,
+    info: 1,
+    minor: 1,
+    moderate: 1,
+};
+/**
+ * Map common severity aliases to canonical values.
+ */
+function normalizeSeverity(severity) {
+    const lower = (severity || "info").toLowerCase();
+    switch (lower) {
+        case "error":
+        case "critical":
+            return "error";
+        case "warning":
+        case "serious":
+            return "warning";
+        default:
+            return "info";
+    }
+}
+/**
+ * Get severity rank for comparison.
+ */
+function severityRank(severity) {
+    return SEVERITY_RANK[severity.toLowerCase()] ?? 0;
+}
+/**
+ * Normalize issues from various API response formats to array.
+ */
+function normalizeIssues(issues) {
+    if (Array.isArray(issues)) {
+        return issues;
+    }
+    if (issues && typeof issues === "object") {
+        const values = Object.values(issues);
+        return values.flatMap((value) => Array.isArray(value) ? value : []);
+    }
+    return [];
+}
+/**
+ * Count issues by normalized severity.
+ */
+function countBySeverity(issues) {
+    const counts = { error: 0, warning: 0, info: 0 };
+    for (const issue of issues) {
+        const normalized = normalizeSeverity(issue.severity || "info");
+        counts[normalized]++;
+    }
+    return counts;
+}
+/**
+ * Extract numeric scores from audit result.
+ */
+function extractScores(scores) {
+    const result = {};
+    if (!scores)
+        return result;
+    for (const [key, value] of Object.entries(scores)) {
+        if (typeof value === "number" && Number.isFinite(value)) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Create empty baseline for when no baseline is provided.
+ */
+function createEmptyBaseline() {
+    return {
+        version: 1,
+        created: new Date().toISOString(),
+        updated: new Date().toISOString(),
+        url: "",
+        issues: [],
+    };
+}
+/**
+ * Evaluate quality gate based on audit results.
+ *
+ * Evaluation order:
+ * 1. Check bypass labels (short-circuit if matched)
+ * 2. Compute diff against baseline (new vs existing)
+ * 3. Count new issues by severity
+ * 4. Check thresholds against scores
+ * 5. Build violations list
+ * 6. Determine exit code
+ *
+ * @param options - Evaluation options
+ * @returns Quality gate result with pass/fail status and violations
+ */
+export function evaluateQualityGate(options) {
+    const { auditResult, baseline, config, labels = [] } = options;
+    // Initialize summary
+    const scores = extractScores(auditResult.scores);
+    const summary = {
+        newIssues: { error: 0, warning: 0, info: 0 },
+        fixedIssues: 0,
+        existingIssues: 0,
+        scores,
+    };
+    // 1. Check bypass labels first
+    const matchedBypass = config.bypassLabels.find((bypassLabel) => labels.some((prLabel) => prLabel.toLowerCase() === bypassLabel.toLowerCase()));
+    if (matchedBypass) {
+        return {
+            passed: true,
+            exitCode: ExitCode.SUCCESS,
+            violations: [],
+            summary,
+            bypassed: true,
+            bypassReason: `Label "${matchedBypass}" bypasses quality gate`,
+        };
+    }
+    // 2. Normalize issues and compute diff
+    const currentIssues = normalizeIssues(auditResult.issues);
+    // Use provided baseline or empty baseline (treats all issues as new)
+    const effectiveBaseline = baseline || createEmptyBaseline();
+    const diff = computeDiff(currentIssues, effectiveBaseline);
+    // Update summary
+    summary.newIssues = countBySeverity(diff.new);
+    summary.fixedIssues = diff.summary.fixedCount;
+    summary.existingIssues = diff.summary.presentCount;
+    // 3. Build violations list
+    const violations = [];
+    // 3a. Check new issues against failOn severity
+    if (config.failOn !== "none") {
+        const failOnRank = severityRank(config.failOn);
+        for (const issue of diff.new) {
+            const issueSeverity = issue.severity || "info";
+            if (severityRank(issueSeverity) >= failOnRank) {
+                violations.push({
+                    type: "new_issue",
+                    severity: normalizeSeverity(issueSeverity),
+                    message: `New ${issueSeverity} issue: ${issue.ruleId || issue.rule_id || issue.id || "unknown"} - ${(issue.description || issue.title || "").slice(0, 100)}`,
+                    details: {
+                        ruleId: issue.ruleId || issue.rule_id || issue.id,
+                        selector: issue.selector,
+                    },
+                });
+            }
+        }
+    }
+    // 3b. Check existing issues if failOnExisting is enabled (legacy mode)
+    if (config.failOnExisting && config.failOn !== "none") {
+        const failOnRank = severityRank(config.failOn);
+        for (const issue of diff.present) {
+            const issueSeverity = issue.severity || "info";
+            if (severityRank(issueSeverity) >= failOnRank) {
+                violations.push({
+                    type: "new_issue", // Using same type for consistency
+                    severity: normalizeSeverity(issueSeverity),
+                    message: `Existing ${issueSeverity} issue: ${issue.ruleId || issue.rule_id || issue.id || "unknown"} - ${(issue.description || issue.title || "").slice(0, 100)}`,
+                    details: {
+                        ruleId: issue.ruleId || issue.rule_id || issue.id,
+                        selector: issue.selector,
+                    },
+                });
+            }
+        }
+    }
+    // 3c. Check max new counts
+    for (const [severityKey, max] of Object.entries(config.maxNew)) {
+        const severity = severityKey;
+        const count = summary.newIssues[severity];
+        if (count > max) {
+            violations.push({
+                type: "max_exceeded",
+                severity,
+                message: `Too many new ${severity} issues: ${count} (max allowed: ${max})`,
+                details: {
+                    count,
+                    threshold: max,
+                },
+            });
+        }
+    }
+    // 3d. Check score thresholds
+    for (const [category, threshold] of Object.entries(config.thresholds)) {
+        if (threshold === undefined)
+            continue;
+        const actual = scores[category];
+        if (actual !== undefined && actual < threshold) {
+            violations.push({
+                type: "threshold",
+                severity: "error",
+                message: `${category} score ${actual} is below threshold ${threshold}`,
+                details: {
+                    actual,
+                    threshold,
+                },
+            });
+        }
+    }
+    // 4. Determine exit code
+    let exitCode = ExitCode.SUCCESS;
+    if (violations.length > 0) {
+        // Check if any threshold violations exist
+        const hasThresholdViolation = violations.some((v) => v.type === "threshold");
+        // Check if any new issue or max exceeded violations exist
+        const hasIssueViolation = violations.some((v) => v.type === "new_issue" || v.type === "max_exceeded");
+        // Exit code 1 (issues) takes precedence over exit code 3 (threshold)
+        if (hasIssueViolation) {
+            exitCode = ExitCode.ISSUES_FOUND;
+        }
+        else if (hasThresholdViolation) {
+            exitCode = ExitCode.THRESHOLD_BREACH;
+        }
+    }
+    return {
+        passed: violations.length === 0,
+        exitCode,
+        violations,
+        summary,
+        bypassed: false,
+    };
+}
+/**
+ * Format quality gate result for human-readable output.
+ */
+export function formatQualityGateResult(result) {
+    const lines = [];
+    // Header
+    if (result.bypassed) {
+        lines.push(`Quality Gate: BYPASSED (${result.bypassReason})`);
+    }
+    else if (result.passed) {
+        lines.push("Quality Gate: PASSED");
+    }
+    else {
+        lines.push("Quality Gate: FAILED");
+    }
+    // Summary
+    lines.push("");
+    lines.push("Summary:");
+    lines.push(`  New issues: ${result.summary.newIssues.error} errors, ${result.summary.newIssues.warning} warnings, ${result.summary.newIssues.info} info`);
+    lines.push(`  Fixed: ${result.summary.fixedIssues}`);
+    lines.push(`  Existing: ${result.summary.existingIssues}`);
+    // Scores
+    const scoreEntries = Object.entries(result.summary.scores);
+    if (scoreEntries.length > 0) {
+        lines.push("");
+        lines.push("Scores:");
+        for (const [category, score] of scoreEntries) {
+            lines.push(`  ${category}: ${score}`);
+        }
+    }
+    // Violations
+    if (result.violations.length > 0) {
+        lines.push("");
+        lines.push(`Violations (${result.violations.length}):`);
+        for (const violation of result.violations) {
+            lines.push(`  - [${violation.severity.toUpperCase()}] ${violation.message}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/quality-gate/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Quality gate module for CI/CD integration.
+ *
+ * Exports evaluator and types for build gating based on audit results.
+ */
+export { evaluateQualityGate, formatQualityGateResult } from "./evaluator.js";
+export type { AuditResultForGate, EvaluateOptions, } from "./evaluator.js";
+export { DEFAULT_QUALITY_GATE_CONFIG } from "./types.js";
+export type { QualityGateConfig, QualityGateResult, GateViolation, ThresholdConfig, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/quality-gate/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/quality-gate/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAC9E,YAAY,EACV,kBAAkB,EAClB,eAAe,GAChB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AACzD,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,eAAe,GAChB,MAAM,YAAY,CAAC"}

package/dist/quality-gate/index.js

@@ -0,0 +1,7 @@
+/**
+ * Quality gate module for CI/CD integration.
+ *
+ * Exports evaluator and types for build gating based on audit results.
+ */
+export { evaluateQualityGate, formatQualityGateResult } from "./evaluator.js";
+export { DEFAULT_QUALITY_GATE_CONFIG } from "./types.js";

package/dist/quality-gate/types.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Quality gate type definitions.
+ *
+ * Quality gates control when CI builds should fail based on audit results.
+ * Key principle: Fail only on NEW issues (not existing technical debt).
+ *
+ * Implements CICD-06: Fail on new issues only, not existing technical debt.
+ */
+import type { ExitCodeType } from "../utils/exit-codes.js";
+/**
+ * Quality gate configuration.
+ */
+export interface QualityGateConfig {
+    /** Fail on issues at or above this severity. 'none' disables severity check. */
+    failOn: "error" | "warning" | "info" | "none";
+    /** Score thresholds (0-100). Undefined means threshold not enforced. */
+    thresholds: ThresholdConfig;
+    /** Maximum allowed new issues by severity */
+    maxNew: {
+        error: number;
+        warning: number;
+        info: number;
+    };
+    /** Whether to fail on existing issues (legacy mode, default: false) */
+    failOnExisting: boolean;
+    /** PR labels that bypass quality gate entirely */
+    bypassLabels: string[];
+}
+/**
+ * Score threshold configuration.
+ *
+ * Each field is optional - only specified thresholds are enforced.
+ */
+export interface ThresholdConfig {
+    /** Overall score threshold (0-100) */
+    overall?: number;
+    /** Accessibility score threshold (0-100) */
+    accessibility?: number;
+    /** UX score threshold (0-100) */
+    ux?: number;
+    /** Performance score threshold (0-100) */
+    performance?: number;
+}
+/**
+ * Individual quality gate violation.
+ *
+ * Violations are categorized by type for clear reporting:
+ * - new_issue: A new issue above failOn severity
+ * - threshold: Score below minimum threshold
+ * - max_exceeded: More new issues than allowed by maxNew config
+ */
+export interface GateViolation {
+    /** Type of violation */
+    type: "new_issue" | "threshold" | "max_exceeded";
+    /** Severity level of the violation */
+    severity: "error" | "warning" | "info";
+    /** Human-readable message */
+    message: string;
+    /** Additional details for debugging */
+    details?: {
+        ruleId?: string;
+        selector?: string;
+        actual?: number;
+        threshold?: number;
+        count?: number;
+    };
+}
+/**
+ * Result of quality gate evaluation.
+ */
+export interface QualityGateResult {
+    /** Whether the gate passed (true = CI should succeed) */
+    passed: boolean;
+    /** Exit code to use for process.exit() */
+    exitCode: ExitCodeType;
+    /** List of violations (empty if passed) */
+    violations: GateViolation[];
+    /** Summary counts for reporting */
+    summary: {
+        newIssues: {
+            error: number;
+            warning: number;
+            info: number;
+        };
+        fixedIssues: number;
+        existingIssues: number;
+        scores: Record<string, number>;
+    };
+    /** Whether gate was bypassed via label */
+    bypassed: boolean;
+    /** Reason for bypass (label name) */
+    bypassReason?: string;
+}
+/**
+ * Default quality gate configuration.
+ *
+ * Defaults are designed to be adoption-friendly:
+ * - Only fail on errors (not warnings/info)
+ * - Only fail on NEW errors (existing debt allowed)
+ * - No score thresholds by default (opt-in)
+ */
+export declare const DEFAULT_QUALITY_GATE_CONFIG: QualityGateConfig;
+//# sourceMappingURL=types.d.ts.map