@owasp-aghast/aghast 0.8.4 → 0.9.0-rc.1

package/dist/result-handlers/pr-comment-handler.js

@@ -0,0 +1,381 @@
+/**
+ * GitHub PR comment result handler (Phase 1 of Spec E.7).
+ *
+ * Posts aghast scan findings as inline review comments on a GitHub pull request.
+ * Issues that fall outside the PR diff are skipped (with a debug log). Existing
+ * comments authored by aghast are deduplicated using a hidden HTML marker
+ * embedded in the comment body.
+ *
+ * Phase-1 limitations (intentional):
+ *   - Multi-line findings (`endLine > startLine`) are anchored at `startLine`
+ *     only; we do not yet emit GitHub's multi-line `start_line`/`line` form.
+ *   - Dedup is best-effort and per-run: two parallel runs (e.g. CI matrix
+ *     shards) on the same PR can each pass the dedup check and post duplicate
+ *     comments. Confine `--pr` to a single matrix shard, or run after the
+ *     matrix completes. A future phase could PATCH instead of POST.
+ *
+ * Future phases (issue tracker integration, AI remediation, IDE/LSP, Slack/email
+ * notifications) are intentionally out of scope here — see GitHub issue #119.
+ */
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { appendFileSync } from 'node:fs';
+import { logDebug, logProgress, logWarn } from '../logging.js';
+const TAG = 'pr-comment-handler';
+// ─── Default executor (real `gh` shell-out) ──────────────────────────────────
+/**
+ * Test-only fake executor selector.
+ *
+ * When `AGHAST_PR_COMMENT_FAKE_FILES` is set, `gh api .../pulls/<n>/files` calls
+ * resolve to the JSON contents of that file. When `AGHAST_PR_COMMENT_FAKE_LOG`
+ * is set, every captured call (including POST bodies) is appended as JSON-lines
+ * to that path. The real `gh` is never spawned. This is used by CLI integration
+ * tests so we can exercise the full --pr code path without hitting GitHub.
+ */
+function maybeFakeExecutor() {
+    const filesPath = process.env.AGHAST_PR_COMMENT_FAKE_FILES;
+    const logPath = process.env.AGHAST_PR_COMMENT_FAKE_LOG;
+    const commentsPath = process.env.AGHAST_PR_COMMENT_FAKE_COMMENTS;
+    if (!filesPath && !logPath && !commentsPath)
+        return undefined;
+    return async (command, args) => {
+        if (logPath) {
+            try {
+                appendFileSync(logPath, JSON.stringify({ command, args }) + '\n', 'utf-8');
+            }
+            catch {
+                // Best-effort logging only.
+            }
+        }
+        const apiPath = args[args.length - 1] ?? '';
+        if (/\/files(\?|$)/.test(apiPath) && filesPath) {
+            const { readFileSync } = await import('node:fs');
+            return { stdout: readFileSync(filesPath, 'utf-8'), stderr: '', exitCode: 0 };
+        }
+        if (/\/comments(\?|$)/.test(apiPath)) {
+            if (commentsPath) {
+                const { readFileSync } = await import('node:fs');
+                return { stdout: readFileSync(commentsPath, 'utf-8'), stderr: '', exitCode: 0 };
+            }
+            return { stdout: '[]', stderr: '', exitCode: 0 };
+        }
+        if (/\/reviews(\?|$)/.test(apiPath)) {
+            return { stdout: '{"id":1}', stderr: '', exitCode: 0 };
+        }
+        return { stdout: '[]', stderr: '', exitCode: 0 };
+    };
+}
+export const defaultExecutor = (command, args, options = {}) => {
+    return new Promise((resolvePromise, reject) => {
+        const child = spawn(command, args, {
+            env: { ...process.env, ...(options.env ?? {}) },
+            shell: false,
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString('utf-8');
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString('utf-8');
+        });
+        child.on('error', (err) => {
+            // Translate the most common failure (gh CLI not installed) into an
+            // actionable message. Without this the user sees `Error: spawn gh ENOENT`
+            // and has to guess what to install.
+            if (err.code === 'ENOENT') {
+                reject(new Error(`gh CLI not found on PATH. Install it from https://cli.github.com or set GH_TOKEN and ensure 'gh' is reachable. (original: ${err.message})`));
+                return;
+            }
+            reject(err);
+        });
+        child.on('close', (code) => {
+            resolvePromise({ stdout, stderr, exitCode: code ?? 1 });
+        });
+        if (options.input !== undefined) {
+            child.stdin.end(options.input);
+        }
+        else {
+            child.stdin.end();
+        }
+    });
+};
+// ─── Patch parsing ───────────────────────────────────────────────────────────
+/**
+ * Parse a unified-diff `patch` (as returned by GitHub's PR files API) into the
+ * set of new-file line numbers that were added or modified by the PR.
+ *
+ * GitHub PR review comments can target either the LEFT (base) or RIGHT (head)
+ * side. We only post comments on lines that exist on the head side — i.e. lines
+ * actually changed (added) by this PR — to avoid leaving stale comments on
+ * unchanged code.
+ */
+export function parsePatchAddedLines(patch) {
+    const addedLines = new Set();
+    if (!patch)
+        return addedLines;
+    const lines = patch.split('\n');
+    let newLine = 0;
+    let inHunk = false;
+    // Hunk header format: @@ -<oldStart>,<oldLen> +<newStart>,<newLen> @@
+    const hunkRegex = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/;
+    for (const line of lines) {
+        const hunkMatch = hunkRegex.exec(line);
+        if (hunkMatch) {
+            newLine = Number(hunkMatch[1]);
+            inHunk = true;
+            continue;
+        }
+        // Defensive: ignore patch content (including stray `+` lines from a
+        // malformed patch) until we see the first hunk header. This prevents us
+        // from ever recording line 0 — which would later masquerade as a real
+        // diff line and either skip or anchor a comment at a nonexistent line.
+        if (!inHunk)
+            continue;
+        if (line.startsWith('+') && !line.startsWith('+++')) {
+            addedLines.add(newLine);
+            newLine++;
+        }
+        else if (line.startsWith('-') && !line.startsWith('---')) {
+            // Removed line — does not advance newLine
+        }
+        else if (line.startsWith('\\')) {
+            // "" — ignore, doesn't advance
+        }
+        else {
+            // Context line: present in both old and new.
+            newLine++;
+        }
+    }
+    return addedLines;
+}
+/**
+ * Build a map of file path → set of new-side line numbers changed by the PR.
+ */
+export function buildDiffLineMap(files) {
+    const map = new Map();
+    for (const file of files) {
+        if (!file.patch)
+            continue;
+        map.set(file.filename, parsePatchAddedLines(file.patch));
+    }
+    return map;
+}
+// ─── Comment building ────────────────────────────────────────────────────────
+/**
+ * Stable hash identifying a single (check + file + line + description) tuple.
+ * Embedded as an HTML comment in the body so future runs can recognise — and
+ * skip — comments they previously posted.
+ */
+export function issueHash(issue) {
+    // Description is deliberately NOT in the hash. AI-generated descriptions are
+    // non-deterministic (the LLM may rephrase the same finding across runs), so
+    // including the description would defeat dedup on re-runs. The trade-off: if
+    // an issue at the same (checkId, file, startLine) genuinely changes meaning,
+    // the original comment will not be refreshed — Phase 1 accepts that staleness
+    // in exchange for idempotent re-runs. A future phase can PATCH the existing
+    // comment to refresh stale descriptions.
+    const payload = [
+        issue.checkId,
+        issue.file,
+        issue.startLine,
+    ].join('');
+    return createHash('sha256').update(payload).digest('hex').slice(0, 16);
+}
+const MARKER_PREFIX = '<!-- aghast-issue-id: ';
+const MARKER_SUFFIX = ' -->';
+export function buildCommentBody(issue) {
+    const hash = issueHash(issue);
+    const severity = issue.severity ? ` (${issue.severity})` : '';
+    const lines = [];
+    lines.push(`**aghast: ${issue.checkName}**${severity}`);
+    lines.push('');
+    lines.push(issue.description);
+    if (issue.recommendation) {
+        lines.push('');
+        lines.push(`**Recommendation:** ${issue.recommendation}`);
+    }
+    lines.push('');
+    lines.push(`${MARKER_PREFIX}${hash}${MARKER_SUFFIX}`);
+    return lines.join('\n');
+}
+export function extractMarkerHash(body) {
+    const idx = body.indexOf(MARKER_PREFIX);
+    if (idx === -1)
+        return undefined;
+    const start = idx + MARKER_PREFIX.length;
+    const end = body.indexOf(MARKER_SUFFIX, start);
+    if (end === -1)
+        return undefined;
+    return body.slice(start, end).trim();
+}
+/**
+ * Map a SecurityIssue onto a ReviewComment, or return undefined if the issue's
+ * line is not part of the PR diff.
+ */
+export function issueToReviewComment(issue, diffLines) {
+    const fileLines = diffLines.get(issue.file);
+    if (!fileLines || !fileLines.has(issue.startLine)) {
+        return undefined;
+    }
+    return {
+        path: issue.file,
+        line: issue.startLine,
+        side: 'RIGHT',
+        body: buildCommentBody(issue),
+    };
+}
+async function ghApi(executor, path, options = {}) {
+    const args = ['api'];
+    if (options.method && options.method !== 'GET') {
+        args.push('--method', options.method);
+    }
+    if (options.paginate)
+        args.push('--paginate');
+    args.push('-H', 'Accept: application/vnd.github+json');
+    args.push(path);
+    let input;
+    if (options.body !== undefined) {
+        args.push('--input', '-');
+        input = JSON.stringify(options.body);
+    }
+    // Pass a token via env if provided; we never log or echo it.
+    const env = {};
+    if (options.token)
+        env.GH_TOKEN = options.token;
+    const result = await executor('gh', args, { input, env });
+    if (result.exitCode !== 0) {
+        throw new Error(`gh api ${path} failed (exit ${result.exitCode}): ${result.stderr.trim() || result.stdout.trim()}`);
+    }
+    if (result.stdout.trim() === '') {
+        return undefined;
+    }
+    return JSON.parse(result.stdout);
+}
+async function listPullRequestFiles(executor, ctx) {
+    const path = `repos/${ctx.owner}/${ctx.repo}/pulls/${ctx.prNumber}/files?per_page=100`;
+    return ghApi(executor, path, {
+        paginate: true,
+        token: ctx.githubToken,
+    });
+}
+async function listExistingReviewComments(executor, ctx) {
+    const path = `repos/${ctx.owner}/${ctx.repo}/pulls/${ctx.prNumber}/comments?per_page=100`;
+    return ghApi(executor, path, {
+        paginate: true,
+        token: ctx.githubToken,
+    });
+}
+/**
+ * Upper bound on inline comments in a single review.
+ *
+ * A noisy check against a large diff could otherwise post hundreds of comments
+ * in one API call — unreviewable for the author, and large enough to risk the
+ * request being rejected outright, which loses every comment rather than some.
+ * Truncating is the lesser harm, and it is surfaced in the review body rather
+ * than dropped silently. Mirrors `limitTargets` in the SARIF parser.
+ */
+const DEFAULT_MAX_INLINE_COMMENTS = 50;
+async function postReview(executor, ctx, comments, omitted = 0) {
+    const path = `repos/${ctx.owner}/${ctx.repo}/pulls/${ctx.prNumber}/reviews`;
+    const summary = `aghast posted ${comments.length} finding${comments.length === 1 ? '' : 's'}.`;
+    const body = {
+        event: 'COMMENT',
+        body: omitted > 0
+            ? `${summary} ${omitted} further finding${omitted === 1 ? '' : 's'} ${omitted === 1 ? 'was' : 'were'} not posted inline (capped at ${comments.length} per review) — see the full scan report for the complete list.`
+            : summary,
+        comments,
+    };
+    if (ctx.headSha)
+        body.commit_id = ctx.headSha;
+    await ghApi(executor, path, {
+        method: 'POST',
+        body,
+        token: ctx.githubToken,
+    });
+}
+/**
+ * Post aghast scan issues as inline GitHub PR review comments.
+ *
+ * Workflow:
+ *   1. Fetch the PR's changed-file list and parse each file's diff hunks.
+ *   2. For each issue, compute the corresponding (path, line, RIGHT) target
+ *      and skip issues whose line is outside the diff.
+ *   3. Fetch existing review comments and skip any whose hidden marker hash
+ *      already matches an in-flight comment.
+ *   4. Post the remainder as a single review with `event=COMMENT`.
+ */
+export async function postPRComments(results, ctx, options = {}) {
+    const executor = options.executor ?? maybeFakeExecutor() ?? defaultExecutor;
+    const issues = results.issues ?? [];
+    if (issues.length === 0) {
+        logProgress(TAG, 'No issues to post — skipping PR comment phase');
+        return { posted: 0, skipped: 0 };
+    }
+    logProgress(TAG, `Posting up to ${issues.length} finding(s) to ${ctx.owner}/${ctx.repo}#${ctx.prNumber}`);
+    const files = await listPullRequestFiles(executor, ctx);
+    const diffLines = buildDiffLineMap(files);
+    logDebug(TAG, `PR diff covers ${diffLines.size} file(s) with patch hunks`);
+    // Map issues onto review comments + bucket the skipped ones.
+    const candidates = [];
+    let skippedOutsideDiff = 0;
+    for (const issue of issues) {
+        const comment = issueToReviewComment(issue, diffLines);
+        if (!comment) {
+            skippedOutsideDiff++;
+            logDebug(TAG, `Skipping issue outside PR diff: ${issue.checkId} ${issue.file}:${issue.startLine}`);
+            continue;
+        }
+        candidates.push(comment);
+    }
+    if (candidates.length === 0) {
+        logProgress(TAG, `No issues fell within the PR diff (${skippedOutsideDiff} skipped)`);
+        return { posted: 0, skipped: skippedOutsideDiff };
+    }
+    // Deduplicate against existing review comments.
+    let existing = [];
+    try {
+        existing = await listExistingReviewComments(executor, ctx);
+    }
+    catch (err) {
+        logWarn(TAG, `Failed to list existing PR comments — skipping dedup: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const existingHashes = new Set();
+    for (const c of existing) {
+        const h = extractMarkerHash(c.body);
+        if (h)
+            existingHashes.add(h);
+    }
+    const toPost = [];
+    let skippedDuplicate = 0;
+    for (const comment of candidates) {
+        const h = extractMarkerHash(comment.body);
+        if (h && existingHashes.has(h)) {
+            skippedDuplicate++;
+            logDebug(TAG, `Skipping duplicate comment ${h} on ${comment.path}:${comment.line}`);
+            continue;
+        }
+        toPost.push(comment);
+    }
+    const totalSkipped = skippedOutsideDiff + skippedDuplicate;
+    if (toPost.length === 0) {
+        logProgress(TAG, `Nothing new to post (${skippedOutsideDiff} outside diff, ${skippedDuplicate} duplicate)`);
+        return { posted: 0, skipped: totalSkipped };
+    }
+    const maxComments = options.maxComments ?? DEFAULT_MAX_INLINE_COMMENTS;
+    const capped = toPost.slice(0, maxComments);
+    const omitted = toPost.length - capped.length;
+    if (omitted > 0) {
+        logWarn(TAG, `${toPost.length} comments to post exceeds the cap of ${maxComments}; ` +
+            `posting the first ${capped.length} and noting the remaining ${omitted} in the review summary. ` +
+            'All findings remain in the scan report.');
+    }
+    await postReview(executor, ctx, capped, omitted);
+    logProgress(TAG, `Posted ${capped.length} comment(s); skipped ${totalSkipped} (${skippedOutsideDiff} outside diff, ${skippedDuplicate} duplicate)`);
+    // Only present when something was actually omitted, so the result shape is
+    // unchanged for the overwhelmingly common case (and for existing consumers).
+    return omitted > 0
+        ? { posted: capped.length, skipped: totalSkipped, omitted }
+        : { posted: capped.length, skipped: totalSkipped };
+}
+//# sourceMappingURL=pr-comment-handler.js.map

package/dist/result-handlers/pr-comment-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pr-comment-handler.js","sourceRoot":"","sources":["../../src/result-handlers/pr-comment-handler.ts"],"names":[],"mappings":"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"}

package/dist/retry.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Retry helper with exponential backoff and an optional shared circuit breaker.
+ *
+ * Spec Appendix E.6 — Retry and Resilience.
+ *
+ * Default classifier retries on rate-limit (429), 5xx, network/timeout errors;
+ * does NOT retry auth errors (401/403) or validation errors. Callers can override
+ * via `isRetryable`.
+ *
+ * The circuit breaker is shared across every `withRetry` invocation that
+ * receives the same `CircuitBreaker` instance. Within a single scan that
+ * means concurrent target analyses share one breaker; across multiple
+ * `runMultiScan` invocations the scope depends on whether the caller hoists
+ * the breaker to module scope or constructs a fresh one per scan (currently
+ * `runMultiScan` does the latter, so the breaker is per-scan, not per-process).
+ * When `consecutiveFailures` reaches the configured threshold, subsequent
+ * calls fail-fast with `CircuitOpenError` without invoking the wrapped
+ * function. A successful call resets the counter.
+ */
+export interface RetryOptions {
+    /** Maximum total attempts (initial + retries). Must be >= 1. */
+    maxAttempts: number;
+    /** Initial backoff delay in ms (before jitter). */
+    baseDelayMs: number;
+    /** Cap on the backoff delay in ms (before jitter). */
+    maxDelayMs: number;
+    /** Optional classifier — return true to retry, false to give up immediately. */
+    isRetryable?: (err: unknown) => boolean;
+    /** Optional shared circuit breaker. */
+    breaker?: CircuitBreaker;
+    /** Optional sleep override (for testing). Defaults to setTimeout. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Optional jitter source returning [0, 1). Defaults to Math.random. */
+    random?: () => number;
+    /** Optional label for log lines. */
+    label?: string;
+}
+/**
+ * Default retry options used when callers don't supply a value.
+ *
+ * `maxAttempts: 1` means retry is OFF unless explicitly configured — one
+ * attempt, no backoff, the original error rethrown untouched. This keeps a
+ * plain `aghast scan` behaving exactly as it did before retry existed.
+ * Opt in with `--retry-max-attempts`, `AGHAST_RETRY_MAX_ATTEMPTS`, or
+ * `retry.maxAttempts` in runtime config.
+ *
+ * The backoff values below are the defaults used *once retry is enabled*;
+ * they have no effect at `maxAttempts: 1`.
+ */
+export declare const DEFAULT_RETRY: Required<Pick<RetryOptions, 'maxAttempts' | 'baseDelayMs' | 'maxDelayMs'>>;
+/** Attempts at or below this mean the caller has not opted into retry. */
+export declare const RETRY_DISABLED_ATTEMPTS = 1;
+/** True when the resolved options leave retry switched off. */
+export declare function isRetryEnabled(maxAttempts: number): boolean;
+/**
+ * Default retryable-error classifier.
+ *
+ * Decision order (first match wins):
+ *   1. HTTP status / statusCode property — authoritative when present.
+ *      4xx (except 429) → not retryable; 429 and 5xx → retryable.
+ *   2. errno-style `code` property (ECONNRESET, ETIMEDOUT, etc.) → retryable.
+ *   3. Free-text message fallback — only consulted when neither status nor
+ *      code matched. Looks for explicit substrings like "rate limit",
+ *      "timed out", "socket hang up". We deliberately do NOT pattern-match
+ *      bare 5xx digits in messages (too prone to false positives — e.g.
+ *      "failed at 500ms timeout" would otherwise be classified retryable).
+ *
+ * Does NOT retry:
+ *   - 401 / 403 (auth)
+ *   - 400 / 404 / 422 (client/validation)
+ *   - Anything classified as fatal by the agent provider (the scan runner
+ *     handles FatalProviderError separately — those never reach this classifier).
+ *   - Unknown errors (callers can pass a custom `isRetryable` to widen this).
+ */
+export declare function defaultIsRetryable(err: unknown): boolean;
+export interface CircuitBreakerOptions {
+    /** Maximum consecutive total failures before tripping. Must be >= 1. */
+    threshold: number;
+}
+/**
+ * Thrown when aghast's own per-call guard fires because a provider call did not
+ * return in time. Distinct from a provider-reported network timeout.
+ *
+ * Named rather than message-matched so the retry decision is deliberate: before
+ * this existed, the classification depended on the word "timeout" appearing in
+ * a free-text message, which is exactly the incidental matching the classifier
+ * warns against elsewhere.
+ *
+ * It IS retryable — a hung stream frequently succeeds on a fresh call — but the
+ * cost is visible: with `maxAttempts: n` a genuinely wedged provider takes up to
+ * n × the timeout to give up. That trade is documented in
+ * docs/configuration.md so anyone enabling retry knows what they are buying.
+ */
+export declare class AgentTimeoutError extends Error {
+    constructor(message: string);
+}
+/** Thrown by `withRetry` when the breaker is open (failing fast). */
+export declare class CircuitOpenError extends Error {
+    constructor(consecutiveFailures: number, threshold: number);
+}
+/**
+ * Process-level circuit breaker. Shared across all `withRetry` calls that
+ * receive the same instance. Counts only TOTAL failures (after all retries
+ * for a single call exhausted), not individual attempts.
+ */
+export declare class CircuitBreaker {
+    private consecutiveFailures;
+    readonly threshold: number;
+    constructor(options: CircuitBreakerOptions);
+    /** True when the breaker is open (further calls should fail-fast). */
+    isOpen(): boolean;
+    /** Increment the failure counter. */
+    recordFailure(): void;
+    /** Reset the failure counter. Called on any successful `withRetry` call. */
+    recordSuccess(): void;
+    /** Force-reset the counter (useful for tests or manual recovery). */
+    reset(): void;
+    /** Current consecutive-failure count (for diagnostics/tests). */
+    getConsecutiveFailures(): number;
+}
+/** Compute the next backoff delay given an attempt number (1-based). */
+export declare function computeBackoff(attempt: number, baseDelayMs: number, maxDelayMs: number, random?: () => number): number;
+/**
+ * Run `fn` with retry on transient errors. Returns its result on success;
+ * throws on the final failure (or `CircuitOpenError` if the breaker is open).
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,MAAM,WAAW,YAAY;IAC3B,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;IACxC,uCAAuC;IACvC,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,qEAAqE;IACrE,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IACtB,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,aAAa,GAAG,aAAa,GAAG,YAAY,CAAC,CAIpG,CAAC;AAEF,0EAA0E;AAC1E,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,+DAA+D;AAC/D,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAkExD;AAID,MAAM,WAAW,qBAAqB;IACpC,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED,qEAAqE;AACrE,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,mBAAmB,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAM3D;AAED;;;;GAIG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,mBAAmB,CAAK;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,OAAO,EAAE,qBAAqB;IAO1C,sEAAsE;IACtE,MAAM,IAAI,OAAO;IAIjB,qCAAqC;IACrC,aAAa,IAAI,IAAI;IAIrB,4EAA4E;IAC5E,aAAa,IAAI,IAAI;IAIrB,qEAAqE;IACrE,KAAK,IAAI,IAAI;IAIb,iEAAiE;IACjE,sBAAsB,IAAI,MAAM;CAGjC;AAID,wEAAwE;AACxE,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,MAAM,MAAoB,GACjC,MAAM,CAOR;AAKD;;;GAGG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC,CAiE1F"}