circle-ir 3.8.4 → 3.9.8

package/dist/graph/dominator-graph.js

@@ -0,0 +1,256 @@
+/**
+ * DominatorGraph
+ *
+ * Computes the dominator tree for a control-flow graph using the
+ * Cooper et al. "A Simple, Fast Dominance Algorithm" (2001).
+ *
+ * Chosen over Lengauer-Tarjan because typical intra-procedural CFGs have
+ * fewer than 100 blocks — O(n²) worst-case is negligible and the algorithm
+ * is straightforward to verify correct.
+ *
+ * Reference:
+ *   Cooper, K.D., Harvey, T.J., Kennedy, K. (2001). "A Simple, Fast Dominance
+ *   Algorithm". Software Practice & Experience, 4, 1–10.
+ *
+ * Design invariants:
+ * - No Node.js-specific APIs. Browser + Node.js + Cloudflare Workers safe.
+ * - Does not mutate the input CFG.
+ * - Unreachable blocks are excluded from all dominator queries.
+ */
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Compute Reverse Post-Order starting from `entryId`.
+ * Returns the RPO traversal order and a map from blockId → RPO position.
+ * Blocks unreachable from `entryId` are excluded.
+ */
+function computeRPO(cfg, entryId) {
+    // Build outgoing adjacency
+    const outgoing = new Map();
+    for (const edge of cfg.edges) {
+        const list = outgoing.get(edge.from) ?? [];
+        list.push(edge.to);
+        outgoing.set(edge.from, list);
+    }
+    // Iterative DFS to compute post-order, then reverse
+    const visited = new Set();
+    const postOrder = [];
+    const stack = [{ id: entryId, childIndex: 0 }];
+    visited.add(entryId);
+    while (stack.length > 0) {
+        const top = stack[stack.length - 1];
+        const children = outgoing.get(top.id) ?? [];
+        // Find next unvisited child
+        let pushed = false;
+        while (top.childIndex < children.length) {
+            const child = children[top.childIndex++];
+            if (!visited.has(child)) {
+                visited.add(child);
+                stack.push({ id: child, childIndex: 0 });
+                pushed = true;
+                break;
+            }
+        }
+        if (!pushed) {
+            // All children visited — add to post-order
+            postOrder.push(top.id);
+            stack.pop();
+        }
+    }
+    const rpoOrder = postOrder.reverse();
+    const rpoIndex = new Map();
+    for (let i = 0; i < rpoOrder.length; i++) {
+        rpoIndex.set(rpoOrder[i], i);
+    }
+    return { rpoOrder, rpoIndex };
+}
+/**
+ * Cooper et al. intersect function.
+ * Walks up the idom tree from b1 and b2 until a common ancestor is found.
+ * Uses RPO positions for comparisons (smaller RPO index = earlier in RPO = closer to entry).
+ *
+ * IMPORTANT: The entry block must have idom[entry] = entry (self-loop sentinel)
+ * so the walk terminates. This sentinel is removed from the public idom map after
+ * computation, but must be present during computation.
+ */
+function intersect(b1, b2, idom, rpoIndex) {
+    let finger1 = b1;
+    let finger2 = b2;
+    while (finger1 !== finger2) {
+        // Walk finger1 up while its RPO position is deeper (larger index) than finger2
+        while ((rpoIndex.get(finger1) ?? Number.MAX_SAFE_INTEGER) >
+            (rpoIndex.get(finger2) ?? Number.MAX_SAFE_INTEGER)) {
+            const parent = idom.get(finger1);
+            if (parent === undefined || parent === finger1)
+                break; // at root or self-loop
+            finger1 = parent;
+        }
+        // Walk finger2 up while its RPO position is deeper than finger1
+        while ((rpoIndex.get(finger2) ?? Number.MAX_SAFE_INTEGER) >
+            (rpoIndex.get(finger1) ?? Number.MAX_SAFE_INTEGER)) {
+            const parent = idom.get(finger2);
+            if (parent === undefined || parent === finger2)
+                break; // at root or self-loop
+            finger2 = parent;
+        }
+        // If neither changed (both at root or unreachable), break
+        if (finger1 === finger2)
+            break;
+        // Safety: if both are at positions we can't walk further, break
+        const rpo1 = rpoIndex.get(finger1) ?? Number.MAX_SAFE_INTEGER;
+        const rpo2 = rpoIndex.get(finger2) ?? Number.MAX_SAFE_INTEGER;
+        if (rpo1 === rpo2 && finger1 !== finger2)
+            break; // can't converge further
+    }
+    return finger1;
+}
+/**
+ * Cooper et al. iterative idom computation.
+ * Requires rpoOrder and rpoIndex from computeRPO.
+ * Returns a map: blockId → immediate dominator blockId.
+ * Entry block has idom[entry] = entry (sentinel) during computation;
+ * callers remove this after the function returns.
+ */
+function computeIdom(cfg, rpoOrder, rpoIndex, entryId) {
+    // Build incoming adjacency
+    const incoming = new Map();
+    for (const edge of cfg.edges) {
+        const list = incoming.get(edge.to) ?? [];
+        list.push(edge.from);
+        incoming.set(edge.to, list);
+    }
+    const idom = new Map();
+    // Initialise: entry block idom = itself (sentinel for termination)
+    idom.set(entryId, entryId);
+    // Iterate until stable
+    let changed = true;
+    while (changed) {
+        changed = false;
+        // Process in RPO order, skip entry (index 0)
+        for (let i = 1; i < rpoOrder.length; i++) {
+            const b = rpoOrder[i];
+            const preds = incoming.get(b) ?? [];
+            // Pick the first predecessor that already has an idom computed
+            // (i.e., already processed in RPO order)
+            let newIdom;
+            for (const p of preds) {
+                if (idom.has(p)) {
+                    newIdom = p;
+                    break;
+                }
+            }
+            if (newIdom === undefined)
+                continue;
+            // Intersect with all other processed predecessors
+            for (const p of preds) {
+                if (p === newIdom)
+                    continue;
+                if (idom.has(p)) {
+                    newIdom = intersect(p, newIdom, idom, rpoIndex);
+                }
+            }
+            if (idom.get(b) !== newIdom) {
+                idom.set(b, newIdom);
+                changed = true;
+            }
+        }
+    }
+    return idom;
+}
+// ---------------------------------------------------------------------------
+// Public class
+// ---------------------------------------------------------------------------
+/**
+ * Dominator tree for a CFG, computed with the Cooper et al. algorithm.
+ *
+ * Entry blocks have no immediate dominator (immediateDominator returns null).
+ * Only blocks reachable from the entry are included.
+ */
+export class DominatorGraph {
+    idom;
+    rpoIndex;
+    entryId;
+    /** Cached reverse map: blockId → all blockIds it strictly dominates. */
+    _dominated = null;
+    constructor(cfg, entryId) {
+        if (cfg.blocks.length === 0) {
+            this.entryId = entryId ?? 0;
+            this.idom = new Map();
+            this.rpoIndex = new Map();
+            return;
+        }
+        // Determine entry: prefer provided entryId, then type='entry' block,
+        // then the block with the smallest id.
+        this.entryId =
+            entryId ??
+                cfg.blocks.find(b => b.type === 'entry')?.id ??
+                cfg.blocks.reduce((a, b) => (a.id < b.id ? a : b)).id;
+        const { rpoOrder, rpoIndex } = computeRPO(cfg, this.entryId);
+        this.rpoIndex = rpoIndex;
+        this.idom = computeIdom(cfg, rpoOrder, rpoIndex, this.entryId);
+        // Remove the sentinel self-reference for the entry block
+        // so immediateDominator(entryId) returns null
+        this.idom.delete(this.entryId);
+    }
+    /**
+     * Returns true if block `a` dominates block `b`.
+     * A block dominates itself (reflexive).
+     */
+    dominates(a, b) {
+        if (a === b)
+            return true;
+        return this.strictlyDominates(a, b);
+    }
+    /**
+     * Returns true if block `a` strictly dominates block `b` (a ≠ b and a dom b).
+     */
+    strictlyDominates(a, b) {
+        if (a === b)
+            return false;
+        // Walk up the idom chain from b; if we reach a, then a dom b.
+        const visited = new Set();
+        let cur = this.idom.get(b);
+        while (cur !== undefined && !visited.has(cur)) {
+            if (cur === a)
+                return true;
+            visited.add(cur);
+            cur = this.idom.get(cur);
+        }
+        return false;
+    }
+    /**
+     * Returns the immediate dominator of `blockId`, or null for the entry block
+     * (or any block not in the dominator tree).
+     */
+    immediateDominator(blockId) {
+        return this.idom.get(blockId) ?? null;
+    }
+    /**
+     * Returns all block IDs strictly dominated by `blockId`.
+     * (Computed lazily and cached on first call.)
+     */
+    dominated(blockId) {
+        if (!this._dominated) {
+            this._dominated = new Map();
+            for (const [child, parent] of this.idom.entries()) {
+                // Walk up from child to find all ancestors (blocks that dominate child)
+                const ancestors = [];
+                const seen = new Set();
+                let cur = parent;
+                while (cur !== undefined && !seen.has(cur)) {
+                    seen.add(cur);
+                    ancestors.push(cur);
+                    cur = this.idom.get(cur);
+                }
+                for (const anc of ancestors) {
+                    const list = this._dominated.get(anc) ?? [];
+                    list.push(child);
+                    this._dominated.set(anc, list);
+                }
+            }
+        }
+        return this._dominated.get(blockId) ?? [];
+    }
+}
+//# sourceMappingURL=dominator-graph.js.map

package/dist/graph/dominator-graph.js.map

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

package/dist/graph/import-graph.d.ts

@@ -0,0 +1,33 @@
+/**
+ * ImportGraph
+ *
+ * Builds a directed file→file import graph from a ProjectGraph.
+ * Only relative imports (from_package starting with '.') are resolved to edges —
+ * stdlib and npm package imports are ignored.
+ *
+ * Used by CircularDependencyPass and OrphanModulePass.
+ */
+import type { ProjectGraph } from './project-graph.js';
+export declare class ImportGraph {
+    /** file → set of files it imports */
+    private readonly outEdges;
+    /** file → set of files that import it */
+    private readonly inEdges;
+    /** All known file paths */
+    private readonly allFiles;
+    constructor(projectGraph: ProjectGraph);
+    /** Files directly imported by `filePath`. */
+    edgesFrom(filePath: string): string[];
+    /** Files that directly import `filePath`. */
+    edgesTo(filePath: string): string[];
+    /**
+     * Tarjan's SCC — returns groups of files that form import cycles.
+     * Each returned Set has size ≥ 2 (only actual cycles).
+     */
+    findCycles(): Set<string>[];
+    /**
+     * Returns file paths with zero incoming import edges that are not entry points.
+     * Entry points: filename base (without extension) matches /^(index|main|app|server|mod)$/i
+     */
+    findOrphans(): string[];
+}

package/dist/graph/import-graph.js

@@ -0,0 +1,170 @@
+/**
+ * ImportGraph
+ *
+ * Builds a directed file→file import graph from a ProjectGraph.
+ * Only relative imports (from_package starting with '.') are resolved to edges —
+ * stdlib and npm package imports are ignored.
+ *
+ * Used by CircularDependencyPass and OrphanModulePass.
+ */
+// ---------------------------------------------------------------------------
+// Path helpers (no Node.js 'path' module — must run in browser too)
+// ---------------------------------------------------------------------------
+function dirname(filePath) {
+    const idx = filePath.lastIndexOf('/');
+    return idx >= 0 ? filePath.slice(0, idx) : '';
+}
+function normalizePath(p) {
+    const isAbsolute = p.startsWith('/');
+    const parts = p.split('/');
+    const result = [];
+    for (const part of parts) {
+        if (part === '' || part === '.')
+            continue;
+        if (part === '..') {
+            result.pop();
+        }
+        else {
+            result.push(part);
+        }
+    }
+    return (isAbsolute ? '/' : '') + result.join('/');
+}
+const EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.py', '.java', '.rs', ''];
+// Entry-point filenames (base without extension) — not treated as orphans
+const ENTRY_POINT_NAMES = /^(index|main|app|server|mod|cli|bin|start|run|entry|init)$/i;
+// ---------------------------------------------------------------------------
+// ImportGraph
+// ---------------------------------------------------------------------------
+export class ImportGraph {
+    /** file → set of files it imports */
+    outEdges;
+    /** file → set of files that import it */
+    inEdges;
+    /** All known file paths */
+    allFiles;
+    constructor(projectGraph) {
+        this.outEdges = new Map();
+        this.inEdges = new Map();
+        this.allFiles = new Set(projectGraph.filePaths);
+        // Initialize edge sets for all files
+        for (const file of this.allFiles) {
+            this.outEdges.set(file, new Set());
+            this.inEdges.set(file, new Set());
+        }
+        // Build edges from imports
+        for (const filePath of projectGraph.filePaths) {
+            const ir = projectGraph.getIR(filePath);
+            if (!ir)
+                continue;
+            const dir = dirname(filePath);
+            for (const imp of ir.imports) {
+                const pkg = imp.from_package;
+                if (!pkg || !pkg.startsWith('.'))
+                    continue; // skip stdlib/npm
+                // Resolve relative path
+                const rawCandidate = dir ? `${dir}/${pkg}` : pkg;
+                const base = normalizePath(rawCandidate);
+                // Try with each extension
+                let resolved = null;
+                for (const ext of EXTENSIONS) {
+                    const candidate = base + ext;
+                    if (this.allFiles.has(candidate)) {
+                        resolved = candidate;
+                        break;
+                    }
+                }
+                // TypeScript ESM convention: `import './foo.js'` refers to `./foo.ts` on disk.
+                // Strip the .js suffix and retry with TypeScript extensions.
+                if (!resolved && base.endsWith('.js')) {
+                    const stripped = base.slice(0, -3);
+                    for (const ext of ['.ts', '.tsx', '.js']) {
+                        const candidate = stripped + ext;
+                        if (this.allFiles.has(candidate)) {
+                            resolved = candidate;
+                            break;
+                        }
+                    }
+                }
+                if (resolved && resolved !== filePath) {
+                    this.outEdges.get(filePath).add(resolved);
+                    this.inEdges.get(resolved).add(filePath);
+                }
+            }
+        }
+    }
+    /** Files directly imported by `filePath`. */
+    edgesFrom(filePath) {
+        return [...(this.outEdges.get(filePath) ?? [])];
+    }
+    /** Files that directly import `filePath`. */
+    edgesTo(filePath) {
+        return [...(this.inEdges.get(filePath) ?? [])];
+    }
+    /**
+     * Tarjan's SCC — returns groups of files that form import cycles.
+     * Each returned Set has size ≥ 2 (only actual cycles).
+     */
+    findCycles() {
+        const index = new Map();
+        const lowlink = new Map();
+        const onStack = new Map();
+        const stack = [];
+        const cycles = [];
+        let counter = 0;
+        const strongConnect = (v) => {
+            index.set(v, counter);
+            lowlink.set(v, counter);
+            counter++;
+            stack.push(v);
+            onStack.set(v, true);
+            for (const w of (this.outEdges.get(v) ?? [])) {
+                if (!index.has(w)) {
+                    strongConnect(w);
+                    lowlink.set(v, Math.min(lowlink.get(v), lowlink.get(w)));
+                }
+                else if (onStack.get(w)) {
+                    lowlink.set(v, Math.min(lowlink.get(v), index.get(w)));
+                }
+            }
+            if (lowlink.get(v) === index.get(v)) {
+                // Root of SCC — pop the component
+                const scc = new Set();
+                let w;
+                do {
+                    w = stack.pop();
+                    onStack.set(w, false);
+                    scc.add(w);
+                } while (w !== v);
+                if (scc.size > 1) {
+                    cycles.push(scc);
+                }
+            }
+        };
+        for (const v of this.allFiles) {
+            if (!index.has(v)) {
+                strongConnect(v);
+            }
+        }
+        return cycles;
+    }
+    /**
+     * Returns file paths with zero incoming import edges that are not entry points.
+     * Entry points: filename base (without extension) matches /^(index|main|app|server|mod)$/i
+     */
+    findOrphans() {
+        const orphans = [];
+        for (const file of this.allFiles) {
+            if ((this.inEdges.get(file)?.size ?? 0) > 0)
+                continue;
+            // Check if entry point
+            const base = file.split('/').pop() ?? '';
+            const baseName = base.includes('.') ? base.slice(0, base.lastIndexOf('.')) : base;
+            if (ENTRY_POINT_NAMES.test(baseName))
+                continue;
+            orphans.push(file);
+        }
+        return orphans.sort();
+    }
+}
+//# sourceMappingURL=import-graph.js.map

package/dist/graph/import-graph.js.map

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

package/dist/graph/index.d.ts

@@ -0,0 +1,5 @@
+export { CodeGraph } from './code-graph.js';
+export { ProjectGraph } from './project-graph.js';
+export { ImportGraph } from './import-graph.js';
+export { DominatorGraph } from './dominator-graph.js';
+export { AnalysisPipeline, type AnalysisPass, type PassContext, type PipelineRunResult, } from './analysis-pass.js';

package/dist/graph/index.js

@@ -0,0 +1,6 @@
+export { CodeGraph } from './code-graph.js';
+export { ProjectGraph } from './project-graph.js';
+export { ImportGraph } from './import-graph.js';
+export { DominatorGraph } from './dominator-graph.js';
+export { AnalysisPipeline, } from './analysis-pass.js';
+//# sourceMappingURL=index.js.map

package/dist/graph/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/graph/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EACL,gBAAgB,GAIjB,MAAM,oBAAoB,CAAC"}

package/dist/graph/project-graph.d.ts

@@ -0,0 +1,43 @@
+/**
+ * ProjectGraph
+ *
+ * Wraps multiple per-file CodeGraph instances with lazy cross-file resolution
+ * infrastructure (SymbolTable, TypeHierarchyResolver, CrossFileResolver).
+ *
+ * Usage:
+ *   const pg = new ProjectGraph();
+ *   pg.addFile('/src/A.java', graphA);
+ *   pg.addFile('/src/B.java', graphB);
+ *   const flows = pg.resolver.findCrossFileTaintFlows();
+ */
+import type { CircleIR } from '../types/index.js';
+import { CodeGraph } from './code-graph.js';
+import { SymbolTable, TypeHierarchyResolver, CrossFileResolver } from '../resolution/index.js';
+export declare class ProjectGraph {
+    private readonly files;
+    private _symbolTable;
+    private _typeHierarchy;
+    private _resolver;
+    /**
+     * Register a file's CodeGraph.  Invalidates all lazy caches.
+     */
+    addFile(filePath: string, graph: CodeGraph): void;
+    /** Registered file paths in insertion order. */
+    get filePaths(): string[];
+    /** Total number of registered files. */
+    get fileCount(): number;
+    /** Retrieve a file's CodeGraph, or undefined if not registered. */
+    getGraph(filePath: string): CodeGraph | undefined;
+    /** Retrieve a file's CircleIR, or undefined if not registered. */
+    getIR(filePath: string): CircleIR | undefined;
+    /** Lazily-built SymbolTable covering all registered files. */
+    get symbolTable(): SymbolTable;
+    /** Lazily-built TypeHierarchyResolver covering all registered files. */
+    get typeHierarchy(): TypeHierarchyResolver;
+    /**
+     * Lazily-built CrossFileResolver.
+     * Accesses `this.symbolTable` and `this.typeHierarchy` (also lazy) so all
+     * three are computed together on the first call after any `addFile()`.
+     */
+    get resolver(): CrossFileResolver;
+}

package/dist/graph/project-graph.js

@@ -0,0 +1,80 @@
+/**
+ * ProjectGraph
+ *
+ * Wraps multiple per-file CodeGraph instances with lazy cross-file resolution
+ * infrastructure (SymbolTable, TypeHierarchyResolver, CrossFileResolver).
+ *
+ * Usage:
+ *   const pg = new ProjectGraph();
+ *   pg.addFile('/src/A.java', graphA);
+ *   pg.addFile('/src/B.java', graphB);
+ *   const flows = pg.resolver.findCrossFileTaintFlows();
+ */
+import { SymbolTable, TypeHierarchyResolver, CrossFileResolver, } from '../resolution/index.js';
+export class ProjectGraph {
+    files = new Map();
+    // Lazy caches — nulled whenever a new file is added
+    _symbolTable = null;
+    _typeHierarchy = null;
+    _resolver = null;
+    /**
+     * Register a file's CodeGraph.  Invalidates all lazy caches.
+     */
+    addFile(filePath, graph) {
+        this.files.set(filePath, { graph, ir: graph.ir });
+        this._symbolTable = null;
+        this._typeHierarchy = null;
+        this._resolver = null;
+    }
+    /** Registered file paths in insertion order. */
+    get filePaths() {
+        return [...this.files.keys()];
+    }
+    /** Total number of registered files. */
+    get fileCount() {
+        return this.files.size;
+    }
+    /** Retrieve a file's CodeGraph, or undefined if not registered. */
+    getGraph(filePath) {
+        return this.files.get(filePath)?.graph;
+    }
+    /** Retrieve a file's CircleIR, or undefined if not registered. */
+    getIR(filePath) {
+        return this.files.get(filePath)?.ir;
+    }
+    /** Lazily-built SymbolTable covering all registered files. */
+    get symbolTable() {
+        if (!this._symbolTable) {
+            const st = new SymbolTable();
+            for (const [path, { ir }] of this.files)
+                st.addFromIR(ir, path);
+            this._symbolTable = st;
+        }
+        return this._symbolTable;
+    }
+    /** Lazily-built TypeHierarchyResolver covering all registered files. */
+    get typeHierarchy() {
+        if (!this._typeHierarchy) {
+            const th = new TypeHierarchyResolver();
+            for (const [path, { ir }] of this.files)
+                th.addFromIR(ir, path);
+            this._typeHierarchy = th;
+        }
+        return this._typeHierarchy;
+    }
+    /**
+     * Lazily-built CrossFileResolver.
+     * Accesses `this.symbolTable` and `this.typeHierarchy` (also lazy) so all
+     * three are computed together on the first call after any `addFile()`.
+     */
+    get resolver() {
+        if (!this._resolver) {
+            const r = new CrossFileResolver(this.symbolTable, this.typeHierarchy);
+            for (const [path, { ir }] of this.files)
+                r.addFile(path, ir);
+            this._resolver = r;
+        }
+        return this._resolver;
+    }
+}
+//# sourceMappingURL=project-graph.js.map

package/dist/graph/project-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-graph.js","sourceRoot":"","sources":["../../src/graph/project-graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAEhC,MAAM,OAAO,YAAY;IACN,KAAK,GAAG,IAAI,GAAG,EAA8C,CAAC;IAE/E,oDAAoD;IAC5C,YAAY,GAAyB,IAAI,CAAC;IAC1C,cAAc,GAAiC,IAAI,CAAC;IACpD,SAAS,GAAkC,IAAI,CAAC;IAExD;;OAEG;IACH,OAAO,CAAC,QAAgB,EAAE,KAAgB;QACxC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,YAAY,GAAK,IAAI,CAAC;QAC3B,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC3B,IAAI,CAAC,SAAS,GAAQ,IAAI,CAAC;IAC7B,CAAC;IAED,gDAAgD;IAChD,IAAI,SAAS;QACX,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAChC,CAAC;IAED,wCAAwC;IACxC,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED,mEAAmE;IACnE,QAAQ,CAAC,QAAgB;QACvB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC;IACzC,CAAC;IAED,kEAAkE;IAClE,KAAK,CAAC,QAAgB;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;IACtC,CAAC;IAED,8DAA8D;IAC9D,IAAI,WAAW;QACb,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,MAAM,EAAE,GAAG,IAAI,WAAW,EAAE,CAAC;YAC7B,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,KAAK;gBAAE,EAAE,CAAC,SAAS,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;YAChE,IAAI,CAAC,YAAY,GAAG,EAAE,CAAC;QACzB,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,wEAAwE;IACxE,IAAI,aAAa;QACf,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;YACzB,MAAM,EAAE,GAAG,IAAI,qBAAqB,EAAE,CAAC;YACvC,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,KAAK;gBAAE,EAAE,CAAC,SAAS,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;YAChE,IAAI,CAAC,cAAc,GAAG,EAAE,CAAC;QAC3B,CAAC;QACD,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;IAED;;;;OAIG;IACH,IAAI,QAAQ;QACV,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,MAAM,CAAC,GAAG,IAAI,iBAAiB,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;YACtE,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,KAAK;gBAAE,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAC7D,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;QACrB,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;CACF"}