@infograb/docker-slim-advisor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 docker-slim-advisor contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,274 @@
+# docker-slim-advisor
+
+Static Dockerfile analyzer that recommends image size optimizations — no Docker build required.
+
+```bash
+npx @infograb/docker-slim-advisor analyze ./Dockerfile
+```
+
+---
+
+## Quick Start
+
+```bash
+npx @infograb/docker-slim-advisor ./Dockerfile
+```
+
+**Example output** (against a typical Node.js app):
+
+```
+Docker Slim Advisor
+--------------------------------------------------
+
+  File:       Dockerfile
+  Base Image: node:18
+
+Size Prediction
+
+  Before: 1.1GB
+  After:  226.6MB
+
+  [██████░░░░░░░░░░░░░░░░░░░░░░░░]
+
+  Estimated savings: 904.9MB (80% reduction)
+
+Findings (2)
+
+  [HIGH] Use node:18-slim instead of node:18 (DSA001)  Line 1
+    Switching from node:18 (1.0GB) to node:18-slim (200MB) saves ~800MB (80% reduction).
+    Fix: FROM node:18-slim
+    Saves ~800.0MB
+
+  [HIGH] Broad COPY/ADD without .dockerignore optimization (DSA004)  Line 5
+    `COPY .` copies the entire build context. Without a comprehensive .dockerignore,
+    this includes node_modules, .git, build artifacts, and other unnecessary files.
+    Fix: Add node_modules, .git, dist, build, .env to .dockerignore
+    Saves ~104.9MB
+```
+
+---
+
+## Features
+
+- **5 optimization rules** — alpine/slim base swap, RUN layer merge, apt/apk cache cleanup, `.dockerignore` detection, unnecessary package removal
+- **3 output formats** — terminal (TTY-aware), JSON (versioned schema), Markdown
+- **Size prediction** — before/after estimates with ±30% accuracy, no `docker build` needed
+- **CI/CD ready** — structured exit codes, `NO_COLOR` support, stderr/stdout separation
+- **Fast** — analysis completes in under 1 second for typical Dockerfiles
+
+---
+
+## Installation
+
+**Global install:**
+
+```bash
+npm install -g @infograb/docker-slim-advisor
+docker-slim-advisor ./Dockerfile
+```
+
+**One-off with npx (no install):**
+
+```bash
+npx @infograb/docker-slim-advisor ./Dockerfile
+```
+
+**Requirements:** Node.js >= 18
+
+---
+
+## Usage
+
+```
+docker-slim-advisor [dockerfile] [options]
+
+Arguments:
+  dockerfile            Path to Dockerfile (default: "Dockerfile")
+
+Options:
+  -f, --format <format>    Output format: terminal, json, markdown (default: "terminal")
+  -s, --severity <level>   Minimum severity to report: LOW, MEDIUM, HIGH
+  -V, --version            Print version
+  -h, --help               Display help
+```
+
+**Examples:**
+
+```bash
+# Analyze Dockerfile in current directory
+docker-slim-advisor
+
+# Analyze a specific file
+docker-slim-advisor path/to/Dockerfile
+
+# JSON output (machine-readable)
+docker-slim-advisor --format json ./Dockerfile
+
+# Only report HIGH severity findings
+docker-slim-advisor --severity HIGH ./Dockerfile
+
+# Markdown report for documentation
+docker-slim-advisor --format markdown ./Dockerfile > report.md
+```
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0`  | No HIGH severity findings |
+| `1`  | One or more HIGH findings present |
+| `2`  | Error (file not found, parse failure, etc.) |
+
+---
+
+## Output Formats
+
+### Terminal (default)
+
+Color and emoji output when connected to a TTY. Plain text in pipes. Respects `NO_COLOR` environment variable.
+
+```bash
+docker-slim-advisor ./Dockerfile
+```
+
+### JSON
+
+Versioned schema suitable for downstream tooling.
+
+```bash
+docker-slim-advisor --format json ./Dockerfile
+```
+
+```json
+{
+  "schemaVersion": 1,
+  "dockerfilePath": "Dockerfile",
+  "isMultiStage": false,
+  "baseImage": "node:18",
+  "estimatedBeforeSize": {
+    "totalBytes": 1131500000,
+    "humanReadable": "1.1GB"
+  },
+  "estimatedAfterSize": {
+    "totalBytes": 226642400,
+    "humanReadable": "227MB"
+  },
+  "sizeReductionPercent": 80,
+  "totalFindings": 2,
+  "findings": [
+    {
+      "ruleId": "DSA001",
+      "severity": "HIGH",
+      "line": 1,
+      "title": "Use node:18-slim instead of node:18",
+      "description": "Switching from node:18 (1.0GB) to node:18-slim (200MB) saves ~800MB.",
+      "fix": "FROM node:18-slim",
+      "estimatedSavingsBytes": 800000000
+    }
+  ]
+}
+```
+
+### Markdown
+
+```bash
+docker-slim-advisor --format markdown ./Dockerfile
+```
+
+Produces a GitHub-compatible report with a findings table and per-rule detail sections. Suitable for PR comments or documentation.
+
+---
+
+## CI/CD Integration
+
+Use exit codes to fail pipelines on HIGH findings:
+
+```bash
+# Fail CI if any HIGH findings are found
+docker-slim-advisor ./Dockerfile
+if [ $? -eq 1 ]; then
+  echo "Image optimization issues detected. Review the findings above."
+  exit 1
+fi
+```
+
+**GitHub Actions example:**
+
+```yaml
+- name: Analyze Dockerfile
+  run: npx @infograb/docker-slim-advisor ./Dockerfile --severity HIGH
+```
+
+**Pipe-friendly (no color/emoji):**
+
+```bash
+# NO_COLOR disables ANSI codes; plain text is always pipe-safe
+NO_COLOR=1 docker-slim-advisor ./Dockerfile | tee advisor-report.txt
+```
+
+**JSON in scripts:**
+
+```bash
+FINDINGS=$(docker-slim-advisor --format json ./Dockerfile | jq '.totalFindings')
+echo "Found $FINDINGS optimization opportunities"
+```
+
+---
+
+## How It Works
+
+`docker-slim-advisor` performs **static analysis** — it reads and parses your Dockerfile as text, with no Docker daemon or image pull required.
+
+1. **Parse** — Dockerfile is tokenized into a typed instruction AST (`FROM`, `RUN`, `COPY`, `ADD`, etc.). Multi-line `RUN` with backslash continuations are handled correctly.
+2. **Detect** — Multi-stage builds (`multiple FROM` instructions) are detected and reported as already optimized.
+3. **Evaluate rules** — Each of the 5 optimization rules inspects the AST and emits findings with line numbers, rule IDs, and estimated savings.
+4. **Estimate sizes** — A bundled JSON database of 170+ image tags provides base image sizes. Layer size heuristics compute before/after predictions (±30% accuracy).
+5. **Format output** — The result is rendered in the requested format with TTY detection and `NO_COLOR` support.
+
+---
+
+## Optimization Rules
+
+| Rule ID | Severity | Description |
+|---------|----------|-------------|
+| `DSA001` | HIGH | Switch to a slimmer base image (e.g. `node:18` → `node:18-slim`, `node:18-alpine`) |
+| `DSA002` | MEDIUM | Merge multiple `RUN` instructions into one to reduce image layers |
+| `DSA003` | MEDIUM | Clean apt/apk cache in the same `RUN` layer (`--no-install-recommends`, `rm -rf /var/lib/apt/lists/*`) |
+| `DSA004` | HIGH | Add or improve `.dockerignore` to avoid copying unnecessary files via `COPY .` |
+| `DSA005` | LOW | Remove unnecessary packages installed for build-time only (e.g. `curl`, `wget`, `git`) |
+
+---
+
+## Supported Base Images
+
+The bundled database covers **170+ image tags** across **53 base images**, including:
+
+| Image | Image | Image |
+|-------|-------|-------|
+| `alpine` | `node` | `python` |
+| `ubuntu` | `debian` | `golang` |
+| `nginx` | `postgres` | `redis` |
+| `rust` | `ruby` | `php` |
+| `maven` | `gradle` | `eclipse-temurin` |
+| `mongo` | `mysql` | `elasticsearch` |
+| `gcr.io/distroless/*` | `mcr.microsoft.com/dotnet/*` | `pytorch/pytorch` |
+
+Tag variants (e.g. `latest`, `slim`, `alpine`, `bookworm`, version-pinned) are included where available.
+
+---
+
+## Contributing
+
+1. Fork the repository and create a feature branch.
+2. Install dependencies: `npm install`
+3. Run tests: `npm test`
+4. Check types: `npm run lint`
+5. Submit a pull request with a clear description of the change.
+
+To add a new optimization rule, create `src/rules/your-rule.ts` implementing the `Rule` interface, then register it in `src/rules/index.ts`.
+
+---
+
+## License
+
+MIT

package/build/base-image-db-loader.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Base image database loader — reads static JSON bundle, provides
+ * size lookup and smaller-alternative search for the size estimator.
+ */
+/** A smaller alternative image found in the DB */
+export interface AlternativeImage {
+    image: string;
+    tag: string;
+    sizeBytes: number;
+}
+/** Load the static image→size map from bundled JSON */
+export declare function loadImageSizeMap(): Record<string, number>;
+/** Lookup image size by name and tag. Returns undefined if not in DB. */
+export declare function getImageSize(image: string, tag: string, images?: Record<string, number>): number | undefined;
+/** Find a smaller alpine/slim alternative for the given image:tag */
+export declare function findSmallerAlternative(image: string, tag: string, images?: Record<string, number>): AlternativeImage | undefined;

package/build/base-image-db-loader.js

@@ -0,0 +1,72 @@
+/**
+ * Base image database loader — reads static JSON bundle, provides
+ * size lookup and smaller-alternative search for the size estimator.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/** Suffixes to try when searching for slim alternatives */
+const SLIM_SUFFIXES = ['-alpine', '-slim'];
+let cachedImages = null;
+/** Load the static image→size map from bundled JSON */
+export function loadImageSizeMap() {
+    if (cachedImages)
+        return cachedImages;
+    const dbPath = join(__dirname, 'data', 'base-image-db.json');
+    const raw = JSON.parse(readFileSync(dbPath, 'utf-8'));
+    // Normalize: entries may be plain numbers or {compressedBytes} objects
+    const normalized = {};
+    for (const [key, value] of Object.entries(raw.images)) {
+        normalized[key] = typeof value === 'number' ? value : value.compressedBytes;
+    }
+    cachedImages = normalized;
+    return cachedImages;
+}
+/** Lookup image size by name and tag. Returns undefined if not in DB. */
+export function getImageSize(image, tag, images) {
+    const db = images ?? loadImageSizeMap();
+    const key = `${image}:${tag}`;
+    if (db[key] !== undefined)
+        return db[key];
+    if (key === 'scratch:latest' || image === 'scratch')
+        return 0;
+    if (tag === 'latest' && db[image] !== undefined)
+        return db[image];
+    return undefined;
+}
+/** Find a smaller alpine/slim alternative for the given image:tag */
+export function findSmallerAlternative(image, tag, images) {
+    const db = images ?? loadImageSizeMap();
+    const currentSize = getImageSize(image, tag, db);
+    if (currentSize === undefined)
+        return undefined;
+    // Already alpine/slim — no further suggestion
+    if (tag.includes('alpine') || tag.includes('slim'))
+        return undefined;
+    const versionPrefix = tag.match(/^[\d.]+/)?.[0] || '';
+    let best;
+    for (const suffix of SLIM_SUFFIXES) {
+        const candidates = [
+            `${image}:${tag}${suffix}`,
+            versionPrefix ? `${image}:${versionPrefix}${suffix}` : null,
+            `${image}:${suffix.slice(1)}`, // e.g. "alpine"
+        ].filter(Boolean);
+        for (const candidate of candidates) {
+            const size = db[candidate];
+            if (size !== undefined && size < currentSize) {
+                if (!best || size < best.sizeBytes) {
+                    const colonIdx = candidate.indexOf(':');
+                    best = {
+                        image: candidate.slice(0, colonIdx),
+                        tag: candidate.slice(colonIdx + 1),
+                        sizeBytes: size,
+                    };
+                }
+            }
+        }
+    }
+    return best;
+}
+//# sourceMappingURL=base-image-db-loader.js.map

package/build/base-image-db-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-image-db-loader.js","sourceRoot":"","sources":["../src/base-image-db-loader.ts"],"names":[],"mappings":"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"}

package/build/cli.d.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for docker-slim-advisor.
+ *
+ * Parses command-line arguments using commander and routes
+ * to the analysis pipeline. Handles --format flag with
+ * 'terminal' (default), 'json', and 'markdown' values.
+ */
+import { Command } from 'commander';
+import type { Severity, AnalysisResult } from './types.js';
+/** Supported output format values */
+export declare const OUTPUT_FORMATS: readonly ["terminal", "json", "markdown"];
+export type OutputFormat = (typeof OUTPUT_FORMATS)[number];
+/** Parsed CLI options after argument processing */
+export interface CliOptions {
+    format: OutputFormat;
+    severity?: Severity;
+}
+/**
+ * Validate that a format string is one of the accepted values.
+ * Used as commander's argParser callback for --format flag.
+ */
+export declare function parseFormat(value: string): OutputFormat;
+/**
+ * Validate that a severity string is one of the accepted values.
+ * Accepts case-insensitive input (e.g. "high", "HIGH", "High").
+ * Used as commander's argParser callback for --severity flag.
+ */
+export declare function parseSeverity(value: string): Severity;
+/**
+ * Build and return the configured Commander program.
+ * Separated from execution for testability.
+ */
+export declare function createProgram(): Command;
+/**
+ * Parse argv and return structured CLI options + positional args.
+ * Exits with code 2 on invalid arguments (commander default behavior).
+ */
+export declare function parseArgs(argv?: string[]): {
+    options: CliOptions;
+    dockerfilePath: string;
+};
+/**
+ * Run the full analysis pipeline: parse → detect → evaluate rules →
+ * estimate sizes → format output → determine exit code.
+ */
+export declare function analyze(dockerfilePath: string, options: CliOptions): AnalysisResult;

package/build/cli.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for docker-slim-advisor.
+ *
+ * Parses command-line arguments using commander and routes
+ * to the analysis pipeline. Handles --format flag with
+ * 'terminal' (default), 'json', and 'markdown' values.
+ */
+import { Command, InvalidArgumentError } from 'commander';
+import { readFileSync } from 'node:fs';
+import { EXIT_CODE } from './exit-codes.js';
+import { determineExitCode } from './exit-codes.js';
+import { SEVERITY_LEVELS, isValidSeverity, filterBySeverity } from './severity-filter.js';
+import { writeError, writeOutput } from './output.js';
+import { parseDockerfile } from './parser.js';
+import { detectMultiStage } from './multi-stage-detector.js';
+import { rules } from './rules/index.js';
+import { estimateBeforeSize, estimateAfterSize, calcSizeReductionPercent } from './size-estimator.js';
+import { getImageSize } from './data/base-image-db.js';
+import { getFormatter } from './formatters/formatter-dispatcher.js';
+/** Supported output format values */
+export const OUTPUT_FORMATS = ['terminal', 'json', 'markdown'];
+/**
+ * Validate that a format string is one of the accepted values.
+ * Used as commander's argParser callback for --format flag.
+ */
+export function parseFormat(value) {
+    const lower = value.toLowerCase();
+    if (!OUTPUT_FORMATS.includes(lower)) {
+        throw new InvalidArgumentError(`Invalid format '${value}'. Must be one of: ${OUTPUT_FORMATS.join(', ')}`);
+    }
+    return lower;
+}
+/**
+ * Validate that a severity string is one of the accepted values.
+ * Accepts case-insensitive input (e.g. "high", "HIGH", "High").
+ * Used as commander's argParser callback for --severity flag.
+ */
+export function parseSeverity(value) {
+    if (!isValidSeverity(value)) {
+        throw new InvalidArgumentError(`Invalid severity '${value}'. Must be one of: ${SEVERITY_LEVELS.join(', ')}`);
+    }
+    return value.toUpperCase();
+}
+/**
+ * Build and return the configured Commander program.
+ * Separated from execution for testability.
+ */
+export function createProgram() {
+    const program = new Command();
+    program
+        .name('docker-slim-advisor')
+        .description('Statically analyze Dockerfiles to recommend image size optimizations')
+        .version('0.1.0')
+        .argument('[dockerfile]', 'Path to Dockerfile to analyze', 'Dockerfile')
+        .option('-f, --format <format>', `Output format: ${OUTPUT_FORMATS.join(', ')}`, parseFormat, 'terminal')
+        .option('-s, --severity <level>', `Minimum severity to report: ${SEVERITY_LEVELS.join(', ')}`, parseSeverity);
+    return program;
+}
+/**
+ * Parse argv and return structured CLI options + positional args.
+ * Exits with code 2 on invalid arguments (commander default behavior).
+ */
+export function parseArgs(argv) {
+    const program = createProgram();
+    // commander.parse() exits on --help/--version;
+    // commander.parseAsync() not needed since we have no async opts
+    program.parse(argv);
+    const opts = program.opts();
+    const dockerfilePath = program.args[0] ?? 'Dockerfile';
+    return { options: opts, dockerfilePath };
+}
+/**
+ * Run the full analysis pipeline: parse → detect → evaluate rules →
+ * estimate sizes → format output → determine exit code.
+ */
+export function analyze(dockerfilePath, options) {
+    const content = readFileSync(dockerfilePath, 'utf-8');
+    const instructions = parseDockerfile(content);
+    const { isMultiStage } = detectMultiStage(instructions);
+    // Determine base image from the first FROM instruction
+    const fromInstr = instructions.find((i) => i.type === 'FROM');
+    const baseImage = fromInstr
+        ? `${fromInstr.image}:${fromInstr.tag}`
+        : 'unknown';
+    // Build rule context with image size lookup
+    const ruleContext = { getImageSize };
+    // Evaluate all rules against parsed instructions
+    const recommendations = isMultiStage
+        ? []
+        : rules.flatMap((rule) => rule.evaluate(instructions, ruleContext));
+    // Size estimation
+    const beforeSize = estimateBeforeSize(instructions, getImageSize);
+    // Calculate new base image size if alpine-swap is recommended
+    const alpineSwapRec = recommendations.find((r) => r.ruleId === 'DSA001');
+    const newBaseImageBytes = alpineSwapRec
+        ? beforeSize.baseImageBytes - alpineSwapRec.estimatedSavingsBytes
+        : undefined;
+    const afterSize = estimateAfterSize(beforeSize, recommendations, newBaseImageBytes);
+    const sizeReductionPercent = calcSizeReductionPercent(beforeSize.totalBytes, afterSize.totalBytes);
+    return {
+        dockerfilePath,
+        isMultiStage,
+        baseImage,
+        instructions,
+        recommendations,
+        estimatedBeforeSizeBytes: beforeSize.totalBytes,
+        estimatedAfterSizeBytes: afterSize.totalBytes,
+        sizeReductionPercent,
+        schemaVersion: 1,
+    };
+}
+/* Main execution - only runs when invoked directly, not when imported */
+async function main() {
+    try {
+        const { options, dockerfilePath } = parseArgs();
+        // Run analysis pipeline
+        const result = analyze(dockerfilePath, options);
+        // Filter recommendations by severity threshold
+        const filtered = options.severity
+            ? filterBySeverity(result.recommendations, options.severity)
+            : result.recommendations;
+        // Dispatch to the correct formatter based on --format value
+        const formatter = getFormatter(options.format);
+        const output = formatter(result, filtered);
+        writeOutput(output);
+        // Set exit code based on findings
+        process.exitCode = determineExitCode(result.recommendations, options.severity);
+    }
+    catch (err) {
+        writeError(err instanceof Error ? err.message : String(err));
+        process.exitCode = EXIT_CODE.ERROR;
+    }
+}
+// ESM doesn't have require.main === module; detect via argv
+const isDirectRun = process.argv[1] &&
+    (process.argv[1].endsWith('/cli.js') ||
+        process.argv[1].endsWith('/cli.ts'));
+if (isDirectRun) {
+    main();
+}
+//# sourceMappingURL=cli.js.map

package/build/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC1F,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AACtG,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAEpE,qCAAqC;AACrC,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,CAAU,CAAC;AASxE;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IAClC,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,KAAqB,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,oBAAoB,CAC5B,mBAAmB,KAAK,sBAAsB,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC1E,CAAC;IACJ,CAAC;IACD,OAAO,KAAqB,CAAC;AAC/B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,oBAAoB,CAC5B,qBAAqB,KAAK,sBAAsB,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC7E,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC,WAAW,EAAc,CAAC;AACzC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,qBAAqB,CAAC;SAC3B,WAAW,CACV,sEAAsE,CACvE;SACA,OAAO,CAAC,OAAO,CAAC;SAChB,QAAQ,CAAC,cAAc,EAAE,+BAA+B,EAAE,YAAY,CAAC;SACvE,MAAM,CACL,uBAAuB,EACvB,kBAAkB,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAC7C,WAAW,EACX,UAA0B,CAC3B;SACA,MAAM,CACL,wBAAwB,EACxB,+BAA+B,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAC3D,aAAa,CACd,CAAC;IAEJ,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,IAAe;IAIvC,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;IAEhC,+CAA+C;IAC/C,gEAAgE;IAChE,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAEpB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAc,CAAC;IACxC,MAAM,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC;IAEvD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC;AAC3C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,cAAsB,EAAE,OAAmB;IACjE,MAAM,OAAO,GAAG,YAAY,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;IACtD,MAAM,YAAY,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,EAAE,YAAY,EAAE,GAAG,gBAAgB,CAAC,YAAY,CAAC,CAAC;IAExD,uDAAuD;IACvD,MAAM,SAAS,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;IAC9D,MAAM,SAAS,GAAG,SAAS;QACzB,CAAC,CAAC,GAAI,SAAkD,CAAC,KAAK,IAAK,SAAkD,CAAC,GAAG,EAAE;QAC3H,CAAC,CAAC,SAAS,CAAC;IAEd,4CAA4C;IAC5C,MAAM,WAAW,GAAG,EAAE,YAAY,EAAE,CAAC;IAErC,iDAAiD;IACjD,MAAM,eAAe,GAAG,YAAY;QAClC,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC,CAAC;IAEtE,kBAAkB;IAClB,MAAM,UAAU,GAAG,kBAAkB,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;IAElE,8DAA8D;IAC9D,MAAM,aAAa,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC;IACzE,MAAM,iBAAiB,GAAG,aAAa;QACrC,CAAC,CAAC,UAAU,CAAC,cAAc,GAAG,aAAa,CAAC,qBAAqB;QACjE,CAAC,CAAC,SAAS,CAAC;IAEd,MAAM,SAAS,GAAG,iBAAiB,CAAC,UAAU,EAAE,eAAe,EAAE,iBAAiB,CAAC,CAAC;IACpF,MAAM,oBAAoB,GAAG,wBAAwB,CAAC,UAAU,CAAC,UAAU,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC;IAEnG,OAAO;QACL,cAAc;QACd,YAAY;QACZ,SAAS;QACT,YAAY;QACZ,eAAe;QACf,wBAAwB,EAAE,UAAU,CAAC,UAAU;QAC/C,uBAAuB,EAAE,SAAS,CAAC,UAAU;QAC7C,oBAAoB;QACpB,aAAa,EAAE,CAAC;KACjB,CAAC;AACJ,CAAC;AAED,yEAAyE;AACzE,KAAK,UAAU,IAAI;IACjB,IAAI,CAAC;QACH,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,GAAG,SAAS,EAAE,CAAC;QAEhD,wBAAwB;QACxB,MAAM,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;QAEhD,+CAA+C;QAC/C,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ;YAC/B,CAAC,CAAC,gBAAgB,CAAC,MAAM,CAAC,eAAe,EAAE,OAAO,CAAC,QAAQ,CAAC;YAC5D,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC;QAE3B,4DAA4D;QAC5D,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC/C,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAC3C,WAAW,CAAC,MAAM,CAAC,CAAC;QAEpB,kCAAkC;QAClC,OAAO,CAAC,QAAQ,GAAG,iBAAiB,CAAC,MAAM,CAAC,eAAe,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IACjF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,UAAU,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QAC7D,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC;IACrC,CAAC;AACH,CAAC;AAED,4DAA4D;AAC5D,MAAM,WAAW,GACf,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACf,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC;QAClC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;AAEzC,IAAI,WAAW,EAAE,CAAC;IAChB,IAAI,EAAE,CAAC;AACT,CAAC"}